Errors and retries

Distinguish validation errors, limits, insufficient reservation balance, and model unavailability.

Read the HTTP status and detail

An error is returned with an unsuccessful HTTP status and a detail field. Validation errors may also include errors: a list of fields and messages. Do not expect answers in such a response.

Example validation error structure

{
  "detail": "Request validation failed",
  "errors": [
    {
      "field": "body.questions",
      "message": "Questions must use supported types"
    }
  ]
}

The example wording is illustrative. Handle the status and structure, rather than the exact wording of detail.

Statuses

HTTP	Cause	What to do
401	The key is missing, unknown, or revoked	Check the server secret; do not retry with the same key
402	Insufficient available balance for a reservation in paid mode	Check the balance and active reservations
403	The organization is suspended for billing review	Check the organization's status; do not bypass it with new keys
409	The request reservation has already been finalized or expired	Check Usage; do not automatically repeat the action
413	The JSON exceeds the byte limit	Shorten the context or split the task
422	Invalid structure, model name, or rejected context	Correct the request or reduce the context
429	Per-minute limit or daily preview quota	Respect Retry-After if present; daily quotas reset at 00:00 UTC
502	The model is unavailable, returned an invalid response, or timed out	Retry within a limit and with a delay; check Usage after a lost connection
503	The model service is not connected	Check the service status later

Retries must be bounded

For a per-minute 429, use Retry-After and a small random delay across clients. The daily preview quota may return 429 without this header: the message will indicate a reset at 00:00 UTC.

Do not retry 401, 402, 403, 413, or 422 without addressing the cause. For network failures and 502, set a small attempt limit and a total time budget. POST /v1/systemone provides no idempotency guarantee.

The gateway does not charge credits for a request it completed with a model error. Losing the response on your client is a different situation: the server may already have completed the request successfully.