Operations
Errors, request IDs and retries
Errors use a JSON envelope with a stable code and request ID. Payload excerpts are not included.
| HTTP | Code | Client action |
|---|---|---|
| 400 | request_limit_exceeded | Non-retryable. Send exactly one question per request; the service does not split or drop questions. |
| 400 | invalid_request | Non-retryable. Correct the JSON schema or tier header, or stay within the model’s token and option limits. |
| 401 | invalid_api_key | Check key configuration and revocation state. |
| 402 | insufficient_credit | Review the account balance before retrying. |
| 403 | tier_not_allowed | Use a tier permitted by the key. |
| 404 | unknown_model | Refresh the live model catalogue. |
| 409 | idempotency_conflict | Use a new key only for a deliberately new request. |
| 409 | idempotency_replay_unavailable | The attempt settled or its settlement is uncertain. A receipt is returned without replaying an answer or charging again; keep the same key until the outcome is clear. |
| 413 | payload_too_large | Stay within the candidate size bounds: request body up to 6 MiB, state up to 16 KiB, and one image up to 4 MiB decoded and 2,000,000 pixels. Final image validation is pending. |
| 422 | unsupported_modality | Choose a model that supports the requested modality. |
| 429 | rate_limit_exceeded | Wait for Retry-After before retrying. |
| 503 | model_unavailable / capacity_limit | Retry only after the documented wait or capacity issue clears. |
| 504 | inference_timeout | When confirmed uncharged, retry with the same key and body. If settlement is uncertain, keep the same key; do not create a second request. |
Keep retries intentional
5xx errors are retryable unless the guard condition says otherwise. An EU request never fails over outside the EU. Use the response request ID when contacting support.
Exact retry behavior is governed by the live OpenAPI when it is published.