Errors & retries

The error body, every error code with its HTTP status, and when to retry.

Every error answer has the same JSON body:

{
  "error": {
    "code": "INVALID_INPUT",
    "message": "wait must be an integer from 0 to 60 (seconds).",
    "retryable": false,
    "field": "wait"
  }
}

Errors of a finished request (status failed, or a failed item of a batch) use the same error object inside the request object.

#Error codes

A code not listed here is answered with HTTP 502. Treat it like UPSTREAM_5XX and follow retryable.

#Codes inside a request

These appear in the error of a request or a batch item, not as an HTTP error status:

#When to retry

The retryable flag in the body is authoritative. As a rule:

• retryable: true: retry the same call. Wait retry_after_seconds when present (or the Retry-After header), otherwise back off exponentially (for example 1 s, 2 s, 4 s ... up to a minute). Unless the body says otherwise, 429, 503 and 504 answers are retryable; SERVER_RESTARTING and SESSION_UNAVAILABLE always are.
• retryable: false: change something first (fix the input, add credits, sign in to aitopia.ai, raise the cap). Retrying the same call gives the same answer.

Submits are not idempotent: the API has no idempotency keys, and every accepted submit is a new, separately charged run. Before you retry a submit that failed with a 5xx or a network error:

1. If the error body has a request_id, GET /v1/requests/{request_id} first: the run may exist.
2. On 502 UPSTREAM_UNCERTAIN (retryable: false) check the request and your balance; do not retry blindly.
3. On a network error with no answer at all, check GET /v1/account/balance before submitting again.

GET calls (models, requests, balance) are safe to retry at any time.