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

OpenAI-style endpoints
{
"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

StatusCodeWhat to do
400invalid_requestFix the request: the message says what’s wrong and param says where.
400unsupported_contentThe model doesn’t read that kind of file. Remove it or pick a model that does.
400invalid_urlA link in the request didn’t download. The message has the status it answered.
400invalid_imageAn input image couldn’t be used (type, size or link).
400image_not_generatedThe model declined the prompt. Not charged.
400context_length_exceededThe model says the conversation is too long for it. Shorten it or pick a model with a longer context.
400max_tokens_reachedA non-streaming /v1/messages answer reached your max_tokens in the middle of a tool call, so it isn’t a whole message. What was generated is charged. Send it again with a higher max_tokens.
401missing_api_keySend the key in Authorization or x-api-key.
401invalid_api_keyThe key is wrong or revoked.
401expired_api_keyCreate a new key.
402insufficient_quotaThe balance, less what your running requests have set aside, doesn’t cover this request, or it ran out partway through an answer. Add credit under Billing, or ask for less output with a lower max_tokens. When auto-recharge has started a top-up, the message says so: retry a few seconds later.
402key_budget_exceededThe request could take the key past its monthly budget, counting its running requests, or reached it partway. Raise the budget, or wait for next month.
402key_daily_budget_exceededThe same for the key’s daily budget. Raise it, or wait for midnight UTC.
403model_not_allowedThe key isn’t allowed to use this model.
403ip_not_allowedThe key only works from other addresses.
404model_not_foundCheck the model ID on the models page.
404unknown_urlNo such endpoint. Check the path and the base URL.
404video_not_foundNo video with that ID in this workspace.
404image_not_foundNo image request with that ID in this workspace (GET /v1/images/{id}, for requests made with a callback_url).
409video_not_readyThe video isn’t finished: poll it until its status is completed.
409video_failedThe video failed, so there’s nothing to download. Its error says why.
410video_expiredThe video was deleted, from the Library or after its 30 days.
413too_largeThe request or a file is over the limit. Send big files as links.
429rate_limit_exceededWait for retry-after seconds, then retry.
429concurrency_limit_exceededThe workspace already has 32 requests running at once. Retry after retry-after seconds, once one has finished.
500server_errorSomething went wrong on our side. Retry.
502stream_interruptedSent as the last event of a stream that broke off. What streamed before the break is charged, nothing after; retry.
503model_unavailableThe model is down right now. Retry after retry-after seconds, or turn on smart routing. Without retry-after and with x-should-retry: false, the model is up but sends this request an error message every time: don’t resend it unchanged.
503server_restartingZurelay is restarting the machine that had your request. Retry at once: another machine takes it. Not charged, unless a stream had started: then what reached you is charged, as for a stream that broke off.
503storage_unavailableAn image was made but couldn’t be delivered. Not charged; retry.
503service_unavailableA brief problem on our side. Retry.

Retrying

  • Retry 429 and 503, waiting the retry-after header’s seconds (or backing off exponentially), unless the response says x-should-retry: false.
  • Don’t retry other 4xx errors 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 503 with x-should-retry: false for 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.