Error codes

Codes

Code	Meaning
`invalid_request`	The request was malformed, failed validation, or used an unsupported feature or attachment.
`unknown_route`	An API-looking path that does not exist, such as `/chat/completions` on the bare host. The message names the correct route.
`model_unavailable`	The requested model could not be resolved or is not available. The `param` is `model`.
`unauthorized`	The credential is missing, malformed, revoked, or expired.
`forbidden`	Authenticated, but not permitted to perform this action.
`insufficient_quota`	Prepaid balance, plan allowance, or a Free-plan daily allowance is exhausted.
`registered_free_unavailable`	The Free plan cannot serve this request on this credential.
`reservation_invalid`	An Encrypted Free-plan reservation was invalid or replayed; restart the whole send.
`payment_required`	An unfunded Free-plan browser session asked for a paid model.
`provider_error`	An upstream provider returned an error.
`rate_limited`	A rate limit was exceeded.
`unavailable`	The service or upstream is temporarily unavailable.
`internal_error`	Fallback for an unexpected/unclassified error.

Code	Recommended action
`invalid_request`	Fix the request. Do not retry unchanged. Check `message` and `param`.
`model_unavailable`	Pick another model. See List models.
`unauthorized`	Check the `z_sk_` key and `Authorization` header. Do not retry unchanged.
`unknown_route`	Fix the base URL: OpenAI-style clients need it to end in `/v1`.
`forbidden`	Check org role/permissions. Do not retry unchanged.
`insufficient_quota`	Add funds or upgrade, or wait for the reset. Do not retry in a loop.
`payment_required`	Add funds or pick a Free-eligible model, then retry.
`provider_error`	Transient. Retry with backoff. See Retry behavior.
`rate_limited`	Retry after `Retry-After`. See Rate limits.
`unavailable`	Transient. Retry with backoff.
`internal_error`	Retry with backoff; if it persists, contact support with the `X-Request-ID`.