Errors and limits

Error format

Both APIs return errors in this format:

{
  "error": {
    "message": "<ExceptionType: Human-readable error message>",
    "type": "exception_type",
    "code": "error_code"
  }
}

The registry API returns validation errors with a detail field instead.

Status codes

Status	Meaning	Retry?
400	Invalid request or parameters	No, fix the request
401	Missing, invalid or expired token	Once, after getting a new token
403	Missing role, or X-Tenant-ID does not match the token	No
404	Resource not found	No
409	Conflict	No
422	The request is valid but cannot be processed	No
429	Rate limit exceeded	Yes, with backoff
500 and other 5xx	Server error	Yes, with backoff

Rate limits

When you send too many requests, the service answers with 429:

{
  "error": {
    "message": "<RateLimitError: You have exceeded the rate limit. Please try again later.>",
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded"
  }
}

Contact Support if your use case needs higher limits.

Errors during streaming

Once a stream has started, the HTTP status can no longer change. Errors are then delivered inside the stream:

• Chat completions: a notification event with type error, followed by [DONE]. See Streaming events.
• Responses API: an error event followed by response.failed. See Responses API.

Retry strategy

• Retry 429 and 5xx with exponential backoff and jitter, for example after 1, 2, 4 and 8 seconds.
• On 401, get a new token and retry once.
• Do not retry other 4xx errors without changing the request.
• Do not retry a chat request automatically if the agent may already have run tools that change data. Let the user decide.