Skip to navigation

Errors and Status Codes

How the API reports errors, what each HTTP status means, and when to retry

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:

{
"error": {
"message": "Insufficient credits. Top up your balance to continue.",
"type": "insufficient_quota",
"param": null,
"code": "insufficient_credits",
"request_id": "req_3f6c2a9e-5b1d-4c8e-9f70-2a4b6c8d0e1f"
}
}

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

StatusMeaningWhat to do
200 OKThe request succeeded. For async media, a job is returned.Continue. For async jobs, poll the returned job_id.
202 AcceptedAn async job was accepted.Poll GET /v1/jobs/{job_id} until it reaches a terminal state.
400 Bad RequestThe request was malformed or rejected before any work ran: invalid JSON (including NaN or Infinity) or a body that is not a JSON object, a missing or invalid parameter, an endpoint the model does not support, or a prompt blocked by the content policy. Not billed.Fix the request and resend. Do not retry unchanged.
401 UnauthorizedThe API key is missing, malformed, or not found.Verify the Authorization: Bearer sk-empiriolabs-... header and that the key exists in your dashboard.
402 Payment RequiredThe account cannot cover the pay-as-you-go amount required by the request.Add credits on the dashboard Billing page or choose a request fully covered by your remaining plan allowance.
403 ForbiddenThe account or API key cannot make this request, for example a restricted account or a model that is not available on the account.Read the message. Contact support if your account is restricted.
404 Not FoundThe resource does not exist, for example an unknown job_id or model id.Check the id and the endpoint path.
422 Unprocessable EntityThe request was well-formed but could not be fulfilled as sent: a parameter is out of range for the model, or generated media was produced and then blocked by the output content check.Adjust the parameter or prompt. See content moderation below.
429 Too Many RequestsYou exceeded your account rate limit (default 50 requests per minute).Retry with exponential backoff and jitter, and review your request volume.
500, 502, 503, 504A transient server or model-service error.Retry with exponential backoff. If it persists, contact support with the x-request-id.

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.failed event, whose response.error has the code and message; an error event can come just before it. No [DONE] follows.
  • Messages. One error event 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:

{
"error": {
"message": "The input exceeds the model's maximum context length. Shorten the input or lower max_tokens and try again",
"type": "invalid_request_error",
"param": null,
"code": "context_length_exceeded",
"request_id": "req_3f6c2a9e-5b1d-4c8e-9f70-2a4b6c8d0e1f"
}
}

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 429 and 5xx responses with exponential backoff and jitter.
  • Do not blindly retry 400, 401, 402, 403, or 422. 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_id instead 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.