Errors
Updated
Use error.code to identify a refusal and error.retryable to decide whether to retry.
Error body
A request refusal returns an HTTP status and an error envelope. This example shows the held-image refusal.
error.message- A readable description of the refusal.
error.type- The error category.
error.param- The affected field, or null.
error.code- The code your application should handle.
error.retryable- A boolean: true permits an automatic retry; false stops automatic retries.
error.details- Optional machine-readable context, such as a cause or reset.
request_id- The request identifier to include when contacting support.
An HTTP 200 can contain a refusal under an individual question in answers. Check the entries as well as the HTTP status.
Error codes
Held marks an input or route this release does not serve. A held code does not make its feature available.
| Status | Code | Meaning | Retryable |
|---|---|---|---|
| 400 | Code: idempotency_key_reuse | Use the original body with this key, or use a new key for changed work. | No automatic retry. |
| 400 | Code: invalid_idempotency_key | Use a nonblank Idempotency-Key with valid ASCII characters within the accepted length. | No automatic retry. |
| 400 | Code: invalid_request | Correct the JSON, field names, types or encoding before resending. | No automatic retry. |
| 400 | Code: invalid_trace_header | Correct or remove X-Client-Request-Id; its value must be nonblank ASCII within the accepted length. | No automatic retry. |
| 401 | Code: invalid_api_key | Authorization is missing, malformed or unknown; a Playground credential is not accepted as a public bearer key. Use a valid System Zero API key. | No automatic retry. |
| 403 | Code: account_suspended | The account is suspended, blocked or waiting for access. Contact support. | No automatic retry. |
| 403 | Code: auth_error | The API key is revoked or blocked. Replace the key; this response uses authentication_error as its type. | No automatic retry. |
| 403 | Code: https_required | Use the HTTPS base URL. | No automatic retry. |
| 404 | Code: audio_not_available | Held. Audio is not available yet. Send the request without the audio attachment. Remove the audio attachment. | No automatic retry. |
| 404 | Code: committee_not_available | Held. This route is not available. Use standard route. | No automatic retry. |
| 404 | Code: deliberate_not_available | Held. This mode is not available. Use standard mode. | No automatic retry. |
| 404 | Code: document_ | Held. Documents with control characters are not available yet. Remove the control characters and send it again. Document attachments remain unavailable, including after control characters are removed. | No automatic retry. |
| 404 | Code: document_not_available | Held. Documents are not available yet. Send the request without the document attachment. Send document contents as state text without an attachment. | No automatic retry. |
| 404 | Code: document_ | Held. Pictures inside documents are not available yet. Send the document without pictures, or as text. Document attachments remain unavailable, including after pictures are removed. | No automatic retry. |
| 404 | Code: image_not_available | Held. Images are not available yet. Send the request without the image attachment. Remove the image attachment. | No automatic retry. |
| 404 | Code: long_context_not_available | Held. This route is not available. Use a shorter stateless text request; sessions remain held. | No automatic retry. |
| 404 | Code: long_ | Held. This input type is not supported. Remove the long recording. | No automatic retry. |
| 404 | Code: model_not_found | The requested model is not offered. Choose the alias or an available pinned version. | No automatic retry. |
| 404 | Code: unknown_endpoint | The route is unavailable. Check the base URL and path; this response does not mean the API key is invalid. | No automatic retry. |
| 404 | Code: video_not_available | Held. This input type is not supported. Remove the video attachment. | No automatic retry. |
| 405 | Code: method_not_allowed | Use a method from the Allow response header. | No automatic retry. |
| 409 | Code: idempotency_conflict | The same key and body is still running. Wait and retry with that key. | Yes. Follow the response wait. |
| 409 | Code: idempotency_ | The request completed, but the stored answer is unavailable. details.original_status records the original status. A new key starts new work; this is not a replay of the old answer. | No automatic retry. |
| 413 | Code: payload_too_large | Reduce the whole request body. | No automatic retry. |
| 413 | Code: questions_too_large | Send fewer or shorter questions. | No automatic retry. |
| 413 | Code: state_too_large | Shorten the state or reduce nesting. | No automatic retry. |
| 413 | Code: state_too_large_unguarded | Shorten or split the state. | No automatic retry. |
| 422 | Code: injection_suspected | Remove embedded instructions from the input and send changed input. | No automatic retry. |
| 422 | Code: invalid_criteria | Use the supported criteria shape and the served text range. | No automatic retry. |
| 422 | Code: question_too_large | Shorten the affected question. | No automatic retry. |
| 429 | Code: capacity_exhausted | Wait for Retry-After; retry only with bounded client backoff. | Yes. Follow the response wait. |
| 429 | Code: concurrency_limit_exceeded | The account already has its allowed work in flight. Follow Retry-After and reduce concurrency; details include max_concurrent. | Yes. Follow the response wait. |
| 429 | Code: monthly_cap_reached | The workspace reached its monthly decision cap. Follow resets_at and Retry-After; details include monthly_request_cap and used. | Yes. Follow the response wait. |
| 429 | Code: playground_daily_limit | The Playground reached its daily limit. Wait for resets_at; details include daily_limit. | Yes. Follow the response wait. |
| 429 | Code: rate_limit_exceeded | Wait for Retry-After and pace requests to the returned limits. | Yes. Follow the response wait. |
| 429 | Code: workspace_limit_exceeded | Wait for Retry-After and reduce the workspace's concurrent work or input load. | Yes. Follow the response wait. |
| 500 | Code: internal_error | An unexpected failure was caught. Retry after the stated delay; contact support with the request ID if it persists. | Yes. Follow the response wait. |
| 503 | Code: idempotency_unavailable | Replay protection cannot answer. Retry with the same Idempotency-Key after the wait. | Yes. Follow the response wait. |
| 503 | Code: limiter_unavailable | The limiting service cannot answer. Retry after the stated delay. | Yes. Follow the response wait. |
| 503 | Code: maintenance | The API is in maintenance. Wait for Retry-After. | Yes. Follow the response wait. |
| 503 | Code: service_unavailable | Wait for Retry-After; keep the request ID if the failure persists. | Yes. Follow the response wait. |
| 503 | Code: system_zero_unavailable | Wait for Retry-After and retry when retryable is true. | Yes. Follow the response wait. |
| 504 | Code: system_zero_timeout | Shorten the work or inspect the outcome; do not automatically replay unchanged. | No automatic retry. |
While the API is unlisted, a call without a valid key for an active account receives 404 unknown_endpoint. Check the key, workspace access, API host and route.
Retries
x-should-retry matches error.retryable. Stop automatic retries when it is false, including 504 system_zero_timeout.
When a response permits a retry, wait for Retry-After-Ms in milliseconds or Retry-After in seconds. Prefer Retry-After-Ms when both are present.
Keep the decision's Idempotency-Key and JSON body. An idempotency_conflict means the same work is still running; wait before retrying with that key.
After a quiet period, a model pool can start on demand. A cold start can outlast a client's retry window; follow the response flags and wait.
Get help
For a refusal that persists, use Contact and include the response's X-Request-Id.