Error codes
Errors use the OpenAI envelope, so SDK exception types map as usual. Every error also carries docs_url, which links to the matching section on this page.
{
"error": {
"message": "Model 'gpt-4o' not found. See GET /v1/models.",
"type": "invalid_request_error",
"param": null,
"code": "model_not_found",
"docs_url": "https://inferenceapis.com/docs/errors#model_not_found"
}
}| Status | code | Retry? | Meaning |
|---|---|---|---|
| 401 | missing_api_key | No | No Bearer token was sent. |
| 401 | invalid_api_key | No | A token was sent but it does not match any key. |
| 402 | insufficient_balance | After topping up | The prepaid balance is zero or below the cost of the request. |
| 402 | key_spend_limit_reached | When the period resets (Retry-After header), or after raising the limit | The API key has a spend limit (per day, week, month or lifetime, set by the account owner) and has reached it. The account may still have balance; other keys keep working. |
| 402 | account_spend_limit_reached | When the period resets (Retry-After header), or after raising the limit | The whole account has an account-wide spend limit (per day, week or month) and has reached it. Every key on the account is stopped until the period resets. |
| 403 | key_paused | After the key is resumed | The account owner paused this key. Nothing is billed while a key is paused. |
| 403 | key_expired | No | The key had an expiry date and it has passed. |
| 403 | model_not_allowed | No | The key is scoped to a list of models and the request named one that is not on it. |
| 404 | model_not_found | No | The model id is not in the catalog. Ids are case-insensitive; common aliases such as deepseek-chat or whisper-1 are accepted. |
| 400 | wrong_endpoint | No | The model exists but belongs to another endpoint, for example a speech model sent to /v1/chat/completions. |
| 503 | model_unavailable | Yes, or use another model | The model is listed but is not being served right now, either disabled by us or refused by the backend. |
| 400 | unsupported_parameter | No | A Responses API field that needs server-side state was sent: previous_response_id, conversation or background. |
| 413 | input_too_long | No | Speech input over 20,000 characters, or an embedding or rerank request over the per-request limits (1,024 texts; 1,000 documents). |
| 413 | file_too_large | No | An audio upload over 100 MB. |
| 400 | timestamps_unsupported | No | Word timestamps, SRT or VTT were requested from a transcription model that does not produce them. |
| 429 | upstream_rate_limited | Yes, after Retry-After | The inference backend is saturated for that model. This is not a quota: your requests and tokens are not metered per minute or per day. |
| 502 | upstream_error | Yes, with backoff | The inference backend failed or timed out. The message carries what it said. |
| 502 | upstream_auth | Yes, later | The backend refused our credentials. This is our problem, not yours, and it is logged and alerted on our side. |
| 404 | unknown_endpoint | No | The path is not one we serve. Files, Batch, fine-tuning, moderation, image generation and audio translation are not offered. |
| 400 | context_length_exceeded | No | The prompt plus max_tokens does not fit the model's context window. The message states the window size. |
| 400 | invalid_request | No | The body is not valid JSON, a required field is missing, or a value is out of range. |
| 400 | signup_rejected | No | POST /v1/signup refused the email address: malformed, a throwaway domain, already registered, or too many signups from this address today. |
missing_api_key · HTTP 401
What it means. No Bearer token was sent.
Fix. Send the key as Authorization: Bearer <key>. Keys are created on the API Keys page or with POST /v1/signup. If you use an OpenAI SDK, set api_key or the OPENAI_API_KEY variable.
Retry: No · SDK exception: AuthenticationError
invalid_api_key · HTTP 401
What it means. A token was sent but it does not match any key.
Fix. Check for a copy error, a deleted key, or a key from another provider left in OPENAI_API_KEY. Keys are shown once at creation; if it is lost, create a new one on the API Keys page.
Retry: No · SDK exception: AuthenticationError
insufficient_balance · HTTP 402
What it means. The prepaid balance is zero or below the cost of the request.
Fix. Add funds on the Billing page; there is no free credit. If you signed up through POST /v1/signup, the confirmation link is in the email we sent.
Retry: After topping up · SDK exception: PermissionDeniedError (402)
key_spend_limit_reached · HTTP 402
What it means. The API key has a spend limit (per day, week, month or lifetime, set by the account owner) and has reached it. The account may still have balance; other keys keep working.
Fix. Raise or remove the limit on the API Keys page, or use another key. The message says how much was spent and when the counter resets; GET /v1/usage returns the same numbers as JSON. An X-Spend-Limit-Resets-At header carries the reset time.
Retry: When the period resets (Retry-After header), or after raising the limit · SDK exception: PermissionDeniedError (402)
account_spend_limit_reached · HTTP 402
What it means. The whole account has an account-wide spend limit (per day, week or month) and has reached it. Every key on the account is stopped until the period resets.
Fix. Raise or remove the account limit under "Account limits" on the API Keys page. GET /v1/usage shows spent, limit and reset time.
Retry: When the period resets (Retry-After header), or after raising the limit · SDK exception: PermissionDeniedError (402)
key_paused · HTTP 403
What it means. The account owner paused this key. Nothing is billed while a key is paused.
Fix. Resume it on the API Keys page (or with the MCP server's update_api_key tool), or use another key.
Retry: After the key is resumed · SDK exception: PermissionDeniedError
key_expired · HTTP 403
What it means. The key had an expiry date and it has passed.
Fix. Extend the expiry on the API Keys page or create a new key. Expiry is optional; keys without one never expire.
Retry: No · SDK exception: PermissionDeniedError
model_not_allowed · HTTP 403
What it means. The key is scoped to a list of models and the request named one that is not on it.
Fix. Use a model on the key's list (the message names them) or widen the list on the API Keys page. Scoping a key to one cheap model is the usual way to hand a key to a script that must not run an expensive model.
Retry: No · SDK exception: PermissionDeniedError
model_not_found · HTTP 404
What it means. The model id is not in the catalog. Ids are case-insensitive; common aliases such as deepseek-chat or whisper-1 are accepted.
Fix. List the ids with GET /v1/models; the canonical field gives the primary id and aliases the accepted alternatives. Closed models (GPT-4o, Claude, Gemini) are not served; see the model list for open replacements.
Retry: No · SDK exception: NotFoundError
wrong_endpoint · HTTP 400
What it means. The model exists but belongs to another endpoint, for example a speech model sent to /v1/chat/completions.
Fix. Each model's type in GET /v1/models says where it goes: chat and vision to /v1/chat/completions or /v1/responses, embedding to /v1/embeddings, rerank to /v1/rerank, tts to /v1/audio/speech, stt to /v1/audio/transcriptions.
Retry: No · SDK exception: BadRequestError
unsupported_parameter · HTTP 400
What it means. A Responses API field that needs server-side state was sent: previous_response_id, conversation or background.
Fix. Responses are not stored. Send the whole conversation in input on every call, which is what Codex CLI and the OpenAI SDKs do by default when store is false.
Retry: No · SDK exception: BadRequestError
input_too_long · HTTP 413
What it means. Speech input over 20,000 characters, or an embedding or rerank request over the per-request limits (1,024 texts; 1,000 documents).
Fix. Split the input and send several requests. For speech, splitting at sentence boundaries keeps the voice consistent across chunks.
Retry: No · SDK exception: BadRequestError (413)
file_too_large · HTTP 413
What it means. An audio upload over 100 MB.
Fix. Compress to 16 kHz mono (Opus or MP3 at 32 to 64 kbps is fine for transcription) or split the recording.
Retry: No · SDK exception: BadRequestError (413)
timestamps_unsupported · HTTP 400
What it means. Word timestamps, SRT or VTT were requested from a transcription model that does not produce them.
Fix. Use openai/whisper-large-v3 or nvidia/parakeet-tdt-0.6b-v3 for timestamps and subtitles. The Voxtral models return text only.
Retry: No · SDK exception: BadRequestError
upstream_rate_limited · HTTP 429
What it means. The inference backend is saturated for that model. This is not a quota: your requests and tokens are not metered per minute or per day.
Fix. Wait the number of seconds in the Retry-After header and retry; the OpenAI SDKs do this on their own. If it persists for one model, another model of the same class will usually be free.
Retry: Yes, after Retry-After · SDK exception: RateLimitError
upstream_error · HTTP 502
What it means. The inference backend failed or timed out. The message carries what it said.
Fix. Retry with exponential backoff. If a specific request fails every time, the message usually names the field the backend rejected.
Retry: Yes, with backoff · SDK exception: APIConnectionError / InternalServerError
upstream_auth · HTTP 502
What it means. The backend refused our credentials. This is our problem, not yours, and it is logged and alerted on our side.
Fix. Retry in a few minutes or use a model on the other backend; the trust page lists which models run where.
Retry: Yes, later · SDK exception: InternalServerError (502)
unknown_endpoint · HTTP 404
What it means. The path is not one we serve. Files, Batch, fine-tuning, moderation, image generation and audio translation are not offered.
Fix. Available: /v1/chat/completions, /v1/responses, /v1/embeddings, /v1/rerank, /v1/audio/speech, /v1/audio/transcriptions, /v1/models, /v1/signup. The base URL is https://api.inferenceapis.com/v1; a doubled /v1/v1/ from an SDK that appends its own path is the usual cause.
Retry: No · SDK exception: NotFoundError
context_length_exceeded · HTTP 400
What it means. The prompt plus max_tokens does not fit the model's context window. The message states the window size.
Fix. Shorten the conversation (drop or summarise old turns), lower max_tokens, which counts against the window, or switch to a larger model: DeepSeek V4 Flash, V4.1 Flash, V4 Pro, GLM 5.3 and GLM 5.3 Flash take 1,048,576 tokens here, MiniMax M3 524,288, Kimi K2.7 Code and Qwen3-VL 262,144, GPT-OSS 120B and Llama 3.3 70B 131,072. GET /v1/models lists context_length per model.
Retry: No · SDK exception: BadRequestError
invalid_request · HTTP 400
What it means. The body is not valid JSON, a required field is missing, or a value is out of range.
Fix. The message names the field. Validation errors from the model backend (a malformed JSON schema, an unsupported sampling parameter for that model) pass through with the backend's wording.
Retry: No · SDK exception: BadRequestError
signup_rejected · HTTP 400
What it means. POST /v1/signup refused the email address: malformed, a throwaway domain, already registered, or too many signups from this address today.
Fix. Use a real mailbox you can open; the confirmation link we send there activates the account. If the address is already registered, sign in at /login (there is an "Email me a sign-in link" option for accounts without a password) and create a key on the API Keys page instead.
Retry: No · SDK exception: BadRequestError
What you will not see
Requests and tokens are not metered per minute or per day, so there is no quota error. A 429 here always means the inference backend is momentarily saturated for that model, and a retry after Retry-After works. Validation errors from the model itself, such as a malformed JSON schema, pass through with the backend's message and a 400.
Machine-readable versions of this page: /llms.txt and /openapi.json.