Errors

The API uses conventional HTTP status codes. Error responses are JSON with an error object containing a human-readable message:

{
  "error": {
    "message": "Invalid API key"
  }
}

Note

Depending on which layer of the serving stack rejects a request, error may occasionally be a plain string instead of an object. Robust clients should handle both: typeof err.error === 'string' ? err.error : err.error.message.

Status codes

Status	When it happens	What to do
400 Bad Request	Malformed JSON, or the model field is missing.	Fix the request body.
401 Unauthorized	Missing, invalid, or revoked API key.	Check the key and the Authorization header.
404 Not Found	Unknown model, or no serving endpoint for it ("no endpoint for model ...").	Pick a model from GET /v1/models.
429 Too Many Requests	An org or per-key rate limit was exceeded.	Back off and retry; consider raising per-key limits or contacting support for a higher org tier.
502 Bad Gateway	All upstream endpoints for the model failed after retries ("all endpoints exhausted").	Retry with backoff; if persistent, try another model or contact support.
503 Service Unavailable	Authentication or model routing temporarily unavailable.	Retry with backoff — this is transient and not caused by your request.
4xx/5xx (other)	Errors from the underlying model provider are passed through with their original status and body.	Handle per the provider’s error semantics.

Retry guidance

• Retry 429, 502, and 503 with exponential backoff and jitter. Rate-limit responses do not currently include a Retry-After header, so start around one second and double per attempt.
• Do not retry 400, 401, or 404 without changing the request.
• The platform already retries transient upstream failures internally before you ever see a 502, so client-side retries can be conservative.