Errors and Status Codes
Every EmpirioLabs API endpoint returns standard HTTP status codes with an error body in the shape of the API it is compatible with. This page explains the status codes you may see and how to handle each one.
Error response shape
Every OpenAI-compatible endpoint returns a JSON body with an error object. param names the request field the error is about and code is a machine-readable code; either is null when it does not apply:
type follows the HTTP status: insufficient_quota for 402, requests or tokens for a 429 (the limit that was reached, with a code such as rate_limit_exceeded), and server_error for a 5xx. Other errors are invalid_request_error, or a more specific type such as authentication_error.
POST /v1/messages and POST /v1/messages/count_tokens return the Anthropic Messages API shape, {"type": "error", "error": {"type": "...", "message": "..."}, "request_id": "..."}, with error.type named by the status (invalid_request_error for 400, authentication_error for 401, rate_limit_error for 429, overloaded_error for 503). A request longer than the model’s context window reads prompt is too long: ....
The /v1beta Gemini endpoints return the Google API shape, {"error": {"code": 400, "message": "...", "status": "INVALID_ARGUMENT"}}, where code is the HTTP status and status is Google’s name for it. These endpoints use the statuses Google uses: a 422 arrives as 400 INVALID_ARGUMENT, and a 502 as 503 UNAVAILABLE.
Every response also includes an x-request-id header. Include that value when you contact support so we can locate the exact request.
Status codes
Errors during a stream
A streamed response has already returned 200 when it starts, so an error after the first event arrives inside the stream, in the shape of the API you called:
- Chat Completions and Completions. A
data:event whose JSON is an error body in the same shape as an HTTP error,{"error": {"message": "...", "type": "...", "param": null, "code": "..."}}. - Responses. A
response.failedevent, whoseresponse.errorhas thecodeandmessage; anerrorevent can come just before it. No[DONE]follows. - Messages. One
errorevent in the Anthropic error shape, and nothing after it. - Gemini. An error object in the Google error shape, as the last server-sent event or the last element of the JSON array.
An error before the first event returns its HTTP status and error body as usual.
Content moderation: 400 versus 422
Content-policy rejections return one of two status codes, and the difference is whether any generation actually ran:
- 400: the prompt was blocked before generation. Nothing was produced, so the request is not billed. Revise the prompt and try again.
- 422: media was generated and then blocked by the output content check. Because the generation ran, the request is billed at the normal rate for that model.
In both cases the message is generic (“This request violates our content policy and could not be completed. Please revise your prompt and try again.”) and does not name a provider. Revise your input to continue.
Requests longer than the context window
When the input, together with max_tokens if you set it, is longer than the model’s context window, the API returns 400 with the code context_length_exceeded before any generation, and the request is not billed:
Shorten the conversation or lower max_tokens, then send the request again. Each model’s context window is listed in the model catalog and in context_length from GET /v1/models. Agent frameworks that compact a conversation when they receive this code do so automatically.
402 responses with a subscription plan
An active subscription can run a request at a zero credit balance only when the entire request is covered by remaining plan allowance. If any pay-as-you-go amount is required, including the remainder of a partly covered request, your available balance must cover that full amount before work starts.
When the balance is insufficient, the API returns 402 insufficient_credits before generation and consumes neither plan allowance nor pay-as-you-go credits. A past-due, canceled, or expired subscription does not provide plan access.
Retrying safely
- Retry
429and5xxresponses with exponential backoff and jitter. - Do not blindly retry
400,401,402,403, or422. They will keep failing until you change the request, key, balance, or input. - Async media jobs are durable. If a poll returns a transient error, keep polling the same
job_idinstead of resubmitting, so you are not charged twice.
For rate-limit details see Limits and API Keys. For key format and bearer-token setup see Authentication.
