Platform
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
429and503, waiting theretry-afterheader’s seconds (or backing off exponentially), unless the response saysx-should-retry: false. - Don’t retry other
4xxerrors unchanged: they’ll fail the same way. - Failed requests are free, so retrying costs nothing until one succeeds. A stream that broke off partway is charged for what it delivered, and the rare
503withx-should-retry: falsefor its input (see Billing). - 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. You’re charged for the input and the output that reached you before it, nothing after. This is rare: most problems are caught and retried before the first token.
The same kind of event ends a stream whose balance or key budget runs out partway, with insufficient_quota, key_budget_exceeded or key_daily_budget_exceeded. A non-streaming request that runs out partway returns what was written, cut short like an answer that reached max_tokens (finish_reason: "length", or stop_reason: "max_tokens" on /v1/messages), with an x-zurelay-stopped header naming the code.
Questions, or something missing? Ask our support team and we’ll answer by email, usually within a minute.