This page summarises the status codes returned by the gateway, what they mean, and the action to take for each code. If the upstream returns a 4xx or 5xx status, the gateway passes that code through unchanged. In all other cases, the table below applies. It also covers the error body formats for the two compatible specifications, the rules for Anthropic-compatible error.type, and the console screens for checking limits and usage.
Status code
Code
Meaning
Action
400
Invalid request value. The limit for the Anthropic-compatible model list is outside the range of 1–1000, or an attempt was made to resume a stored response with GET /responses/{responseId}?stream=true
Correct the value so that it falls within the permitted range. Retrieve stored responses without stream.
401
Missing, expired, or revoked key
Check the key status on the API key screen, and verify the header name and the Bearer prefix.
403
No access permission for the model, usage limit exceeded, insufficient credits, or not the voice owner
error.message identifies the reason. Check the figures on the screens in the Limits and usage section below.
404
Model does not exist or cannot be accessed with this key (including models that are no longer supported), path does not exist, or CleviDrive output is more than 3 days past its retention period
First check the list of models available to call with GET /models. Compare the path with the table on the Making API calls page.
408 · 409 · 413
Upstream timeout, congestion, or request size exceeded. For voice and voice-related paths, the timeout limit is 5 minutes and the request limit is 28 MiB
If 409 includes Retry-After, wait for the specified time. For 413, split the request into smaller parts.
429
The upstream provider has applied a rate limit
If Retry-After is provided, follow it as-is; otherwise, retry with exponential backoff.
5xx
Temporary error in the gateway or upstream (including 503)
Retry with exponential backoff. If the issue persists, report it through Help and Contact us with X-Request-Id.
Retries
The gateway does not generate its own 429 responses, nor does it silently retry or queue upstream responses. The client handles waiting and retries.
Code
Wait time
Then
409
That duration if Retry-After is present
Send the same request again.
429
That duration if Retry-After is present; exponential backoff if not
Send the same request again.
5xx
Exponential backoff
Contact support if it keeps recurring.
413
No wait
Split the request.
Error body
The format of the error body varies by specification. Upstream errors are cleaned up and forwarded with only the message; stack traces and internal fields are not passed through.
Body for the OpenAI-compatible route.
{"error":{"message":"API key is required.","type":"invalid_request_error"}}
Body for the Anthropic-compatible route. error.type is determined by the status code.
