Errors

Errors come back as JSON in the format of the endpoint you called, with a message written for people and, on the OpenAI-style endpoints, a stable code for programs.

The shape

{
  "error": {
    "message": "This API key can't use `gpt-6-astra`. It's limited to gpt-6-sol. Change that at https://zurelay.com/app/keys.",
    "type": "permission_error",
    "param": "model",
    "code": "model_not_allowed"
  }
}

On /v1/messages the same errors come in Anthropic’s shape, which has no code: use the HTTP status and error.type: { "type": "error", "error": { "type": "...", "message": "..." } }. Every chat, image and video response, error or not, has an x-request-id header.

Codes

Retrying

• Retry 429 and 503, waiting the retry-after header’s seconds (or backing off exponentially).
• Don’t retry other 4xx errors unchanged: they’ll fail the same way.
• Failed requests are free, so retrying costs nothing until one succeeds.
• The official OpenAI and Anthropic SDKs already retry the right errors for you.

Errors mid-stream

Errors a model returns about your request itself (a parameter it doesn’t take, a prompt too long for it) come through with the model’s own message and code, as a 400 or 422.

Errors mid-stream

Once a stream has started, a failure can’t become an HTTP status. You get a final error event instead (in the endpoint’s format) and the stream ends, and the request isn’t charged. This is rare: most problems are caught and retried before the first token.