Error codes

Every HTTP status and error code the Modellane API returns, with the likely cause and the fix, plus the shape of the JSON error body.

Errors come back as JSON with a stable code. This page lists each status the API can return, what usually causes it and what to change.

Every error is a JSON body in the OpenAI error format. Branch on code, which is stable; message is for people and can change.

JSON

{
  "error": {
    "message": "Your balance is insufficient for this request.",
    "type": "insufficient_balance_error",
    "param": null,
    "code": "insufficient_balance"
  }
}

param names the request field that caused the error when there is one, for example messages or max_tokens, and is null otherwise. The OpenAI SDKs raise these as exceptions (BadRequestError, AuthenticationError, RateLimitError and so on) with the body attached.

All codes#

HTTP status	Code	Type	Description
400	`invalid_json`	`invalid_request_error`	The request body is not valid JSON.
400	`invalid_request`	`invalid_request_error`	The request body is malformed or contains an invalid value.
400	`unsupported_parameter`	`invalid_request_error`	The parameter needs server-side state we never keep (for example previous_response_id or background on /v1/responses).
400	`unsupported_content`	`invalid_request_error`	The model does not accept this content type (for example, image input).
400	`image_url_not_supported`	`invalid_request_error`	Image URLs are not fetched. Send the image inline as a base64 data URL (data:image/png\|jpeg\|webp\|gif;base64,...).
400	`context_length_exceeded`	`invalid_request_error`	The prompt and requested output do not fit in the model's context window.
401	`invalid_api_key`	`authentication_error`	The API key is missing, malformed or revoked.
401	`authentication_required`	`authentication_error`	The panel session is missing or expired.
403	`origin_not_allowed`	`permission_error`	The request came from an origin that is not allowed to call the panel API.
402	`insufficient_balance`	`insufficient_balance_error`	The project balance cannot cover the request's reservation.
404	`model_not_found`	`not_found_error`	No active model has this id.
413	`request_too_large`	`invalid_request_error`	The request body exceeds the size limit.
429	`rate_limit_exceeded`	`rate_limit_error`	The project sent too many requests per minute.
429	`concurrency_limit`	`rate_limit_error`	The project has too many requests in flight.
429	`model_capacity`	`rate_limit_error`	The model is temporarily at capacity. Retry after the Retry-After interval.
500	`internal_error`	`api_error`	An unexpected error occurred on our side.
502	`upstream_error`	`api_error`	The model failed to produce a response.
503	`model_unavailable`	`api_error`	The model is temporarily unavailable.
504	`upstream_timeout`	`api_error`	The model did not respond in time.

Causes and fixes#

Code	Cause and solution
400 Invalid request	Cause: the body is not valid JSON (`invalid_json`), a field has a wrong type or value (`invalid_request`), or the prompt plus `max_tokens` is longer than the context window (`context_length_exceeded`). Solution: check `param` and `message`, compare the request with Chat completions, and shorten the history or lower `max_tokens` for context errors.
400 Unsupported content	Cause: the model does not accept a part of the message, usually an image sent to a text-only model (`unsupported_content`), or an image was given as a web URL (`image_url_not_supported`). Solution: pick a model with Vision in Models & pricing and send images inline as base64 data URLs.
401 Authentication failed	Cause: the `Authorization` header is missing, the key is mistyped, or the key was revoked (`invalid_api_key`). Solution: send `Authorization: Bearer <key>` and check the key on the API keys page; create a new one if needed.
402 Insufficient balance	Cause: your available balance cannot cover the hold for this request (`insufficient_balance`). The hold counts up to one token per byte of prompt text plus `max_tokens` of output, and is settled to actual usage. Solution: add credit on the Billing page, or lower `max_tokens` so the hold is smaller. See Deduction rules.
403 Forbidden	Cause: a browser request to the dashboard API from another site (`origin_not_allowed`). Solution: call the API from your server with an API key.
404 Not found	Cause: the `model` value does not match an active model (`model_not_found`). Solution: copy the id from `GET /v1/models`; ids are case sensitive.
413 Request too large	Cause: the body is over 8 MB, or one image is over 5 MB (`request_too_large`). Solution: compress or resize images, and trim long histories.
429 Too many requests	Cause: your project hit its per-minute or concurrency limit (`rate_limit_exceeded`, `concurrency_limit`), or the model is at capacity (`model_capacity`). Solution: wait for the `Retry-After` interval and retry with backoff. See Rate limits.
500 Server error	Cause: an unexpected error on our side (`internal_error`). Solution: retry after a short wait. If it keeps happening, contact us with the time of the request.
502 Upstream error	Cause: the model failed while producing the response (`upstream_error`). Solution: retry. Nothing is billed if no content was returned.
503 Model unavailable	Cause: the model is temporarily offline (`model_unavailable`). Solution: retry later, or switch to another model.
504 Timeout	Cause: the model did not answer in time (`upstream_timeout`). Solution: use `stream: true` for long answers, or lower `max_tokens`.

Errors during a stream#

Once a streamed response has started, the HTTP status is already 200. If the model fails after that point, the API sends one more data: event that holds the usual error body (for example upstream_error or upstream_timeout) and closes the stream without data: [DONE]. The content you received before the error is billed. Treat a stream that ends without [DONE] as incomplete; the OpenAI SDKs raise an exception for the error event.

Retry or not#

Retry with backoff: 429, 500, 502, 503, 504.
Do not retry unchanged: 400, 401, 402, 403, 404, 413. The same request fails the same way until you fix it.