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. |
| 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 | 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. New accounts receive $1 of starter credit once the email address is confirmed; 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)
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
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 starter credit is released by the confirmation link we send there. 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.