OpenRouter
OpenRouter errors and fixes
32 OpenRouter errors from the official error docs, grouped by HTTP status, each with what it means, why it happens, the documented fix and whether to retry. Verified .
- Official error docsopenrouter.ai
- Status pagestatus.openrouter.ai
- OpenRouter rate limits
Error response body
The shape OpenRouter errors come back in, as the official docs show it. Read the status and error type from here before matching an entry below.
Snippet
type ErrorResponse = {
error: {
code: number;
message: string;
metadata?: Record<string, unknown>;
};
};HTTP 400 Bad Request
400 invalid_requestBad Request: a request parameter is malformed or missing (the HTTP error list also cites CORS).Retry? Not stated400 invalid_promptA specific message in the messages array is invalid, for example an unsupported role or empty content.Retry? Not stated400 context_length_exceededThe combined input and output tokens exceed the model's context window. On the Responses API the docs list this among errors transformed into a successful completion with finish_reason length.Retry? Not stated400 max_tokens_exceededGeneration stopped because max_tokens (or max_completion_tokens) was reached.Retry? Not stated400 token_limit_exceededA token budget enforced by OpenRouter, for example a credit-based cap, was exceeded.Retry? Not stated400 string_too_longA single string field in the request (system prompt, user message, etc.) exceeded the provider's per-field character limit.Retry? Not stated400 invalid_imageAn image in the request is corrupt or unreadable.Retry? Not stated400 image_too_largeAn image exceeds the provider's maximum file size or pixel dimensions.Retry? Not stated400 image_too_smallAn image is below the provider's minimum pixel dimensions.Retry? Not stated400 unsupported_image_formatThe image format is not supported by the provider.Retry? Not stated400 image_download_failedOpenRouter could not download the image from the provided URL.Retry? Not stated
HTTP 401 Unauthorized
HTTP 402 Payment Required
402 payment_requiredThe account or API key has insufficient credits. error.metadata.limit_source is openrouter_credits when the balance cannot cover the request, or openrouter_key_limit when the key's credit limit is exhausted. A negative balance can cause 402 even for free models.Retry? No402 in_flight_budget_exhaustedYour running and recently completed paid requests already fill your in-flight spending budget, so the request is rejected before reaching a provider even though the balance is positive. metadata.limit_source is openrouter_in_flight_budget. This is transient and the response includes a Retry-After header.Retry? Yes402 weight_exceeds_budgetThis single request's estimated cost is larger than your whole in-flight budget. metadata.limit_source is openrouter_credits. Retrying will not help.Retry? No
HTTP 403 Forbidden
403 permission_deniedThe key is valid but lacks the required permission, or the request was blocked by a guardrail (for example a content filter or prompt-injection detector) before reaching a provider. On /messages the block is returned as an Anthropic permission_error envelope.Retry? Not stated403 Budget limit exceededA guardrail budget, a workspace budget, or the key's own limit is spent, so the request is rejected before it reaches a provider. error.metadata.limit_source is openrouter_guardrail_budget, openrouter_workspace_budget, or openrouter_key_limit, with scope, limit_usd, spend_usd and resets_at.Retry? No403 content_policy_violationThe input or output was flagged by a content filter that runs separately from the model (provider- or OpenRouter-level), such as Gemini's SAFETY block. For moderation flags, error.metadata carries reasons, flagged_input, provider_name and model_slug.Retry? Not stated403 refusalThe provider reported a model refusal as an error rather than as output. error.message carries the provider's explanation when available. A refusal the model returns as completed output is not an error.Retry? Not stated
HTTP 404 Not Found
HTTP 408 Request Timeout
HTTP 412 Precondition Failed
HTTP 413 Content Too Large
HTTP 422 Unprocessable Content
HTTP 429 Too Many Requests
HTTP 500 Internal Server Error
500 serverAn unexpected internal error. The upstream error message is masked: message is replaced with a generic string and provider_code and openrouter_metadata are omitted, but error_type server is still present.Retry? Not stated500 unmappedAn upstream error that does not map to any known category. error.metadata.provider_code may contain the original code.Retry? Not stated
HTTP 502 Bad Gateway
HTTP 503 Service Unavailable
503 No available model provider meets your routing requirementsThere is no available model provider that meets your routing requirements. OpenRouter may include a Retry-After header on 503 responses indicating how many seconds to wait before retrying.Retry? Yes503 provider_overloadedThe upstream provider is temporarily overloaded. On the Anthropic Messages skin this maps to overloaded_error.Retry? Yes
HTTP 504 Gateway Timeout
Newsletter
Know when the APIs change
One email per week. New model releases, API changes, what broke, and how developers are working around it.