Errors & Retries

What the API returns when something goes wrong, and how to recover.

Every error has the same envelope, whatever its cause. request_id is always present, and retry_after_ms appears when waiting will help.

{
  "error": {
    "type": "rate_limit_exceeded",
    "code": "rate_limit_exceeded",
    "message": "Too many requests.",
    "request_id": "req_...",
    "retry_after_ms": 12000
  }
}

When your workspace sends requests or tokens faster than its limits allow, the API answers 429 with a Retry-After header (in seconds) and retry_after_ms in the body. What the limits are, how they rise, and how to see yours are on Rate Limits.

You can set a purchased credit spend limit on your account, and on each API key, on the Billing and API Keys pages. Choose a daily, weekly or monthly limit (all in UTC; a week runs Monday to Sunday; Monthly is the first choice offered). It protects you from a bug that sends requests in a loop. It counts only what you spend from purchased credit: usage paid for with promotional tokens is never limited and does not count. Once what you have spent from purchased credit in that period reaches it, the API answers 429 with the code spend_limit_reached and a Retry-After header counting down to when the period starts again: 00:00 UTC tomorrow, next Monday, or the 1st of the next month. Requests already running when the limit is reached still finish and are charged, so a period can end a little over it. Raise or remove the limit and requests are accepted again within a minute. Retrying sooner than Retry-After won't help. Only you can set the limit; Aivana never does.

• Retry only 429, 502 and 504, and network failures. Other 4xx errors won't succeed unchanged.
• Wait for the time in Retry-After (or retry_after_ms) when it is given; otherwise back off exponentially, for example 1, 2, 4, then 8 seconds, with a little random jitter.
• Stop after a few attempts and surface the error, with its request_id, to your user or logs.
• A request that failed on Aivana's side isn't charged, so a retry doesn't cost you twice.

from aivana import RateLimitError, UpstreamError

try:
    res = aivana.generate("Summarize our Q3 churn drivers.")
except (RateLimitError, UpstreamError) as err:
    print("Retry later:", err.message, err.request_id)