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, the gateway passes that code through unchanged. Otherwise, it follows the table below. It also describes 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 codes
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 is within the permitted range. Retrieve stored responses without stream.
401
The key is missing, expired or revoked
Check the key status on the API keys page, and verify the header name and Bearer prefix.
403
No access to the model, usage limit exceeded, insufficient credits, or not the voice owner
error.message distinguishes the reason. Check the figures on the screens described in the Limits and usage section below.
404
The model does not exist or cannot be accessed with this key (including models that are no longer supported), the path does not exist, or the 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 audio paths, the timeout is 5 minutes and the request limit is 28 MiB
If 409 includes Retry-After, wait for that amount of time. For 413, split the request into multiple parts.
429
The upstream provider has applied a rate limit
If Retry-After is provided, follow it as specified. Otherwise, retry with exponential backoff.
5xx
A temporary error from the gateway or upstream (including 503)
Retry with exponential backoff. If the issue persists, report it to Help and Contact us with the X-Request-Id.
Retries
The gateway does not generate its own 429 responses, nor does it silently retry or queue upstream responses. The client is responsible for waiting and retrying.
Code
Waiting time
Then
409
If Retry-After is present, wait for that duration
Send the same request again.
429
If Retry-After is present, wait for that duration; otherwise use exponential backoff
Send the same request again.
5xx
Exponential backoff
Contact us if it keeps happening.
413
No waiting
Split the request.
Error body
The format of the error body differs by specification. Upstream errors are passed on in a cleaned-up form with only the message retained; stack traces and internal fields are not passed through.
The body for the OpenAI-compatible path.
{"error":{"message":"API key is required.","type":"invalid_request_error"}}
The body for the Anthropic-compatible path. error.type is determined by the status code.
