Errors

Reference OpenGateway’s JSON error envelopes, emitted HTTP statuses and codes, and next steps for authentication, model, quota, rate-limit, and overload failures.

OpenAI-compatible endpoints return a JSON error body. The status, type, code, and message depend on the failure and endpoint; not every error includes a code or param.

OpenAI-compatible error envelope#

JSON

{
  "error": {
    "message": "The model does not exist or you do not have access to it.",
    "type": "invalid_request_error",
    "code": "model_not_found",
    "param": "model"
  }
}

error.message explains the failure, error.type identifies its category, and error.code and error.param are optional. Honor a Retry-After response header when present. Codes below are those emitted by the current data plane; upstream passthrough routes can preserve provider-specific statuses or error details.

Common errors#

HTTP status	`error.type`	`error.code`	Meaning	What to do
400	`invalid_request_error`	`missing_required_parameter` or absent	A required field is missing or a request parameter is invalid.	Fix the body or field named by `param`; do not retry the same request unchanged.
400	`invalid_request_error`	`model_not_found`	The router cannot find a servable model for this model ID.	Copy the exact current ID from `GET /v1/models` and check that it serves the requested endpoint.
400	`invalid_request_error`	`unsupported_endpoint`	The model exists but does not declare the endpoint being called.	Choose a model whose catalog `endpoints` contains the matching endpoint value.
400	`image_generation_user_error`	Provider-specific or absent	An image-generation request was rejected as a caller error.	Review the prompt and image parameters, then retry only after changing the request.
401	`invalid_request_error`	`invalid_api_key`	The API key is missing, invalid, or inactive.	Check the key and send it as `Authorization: Bearer <key>`.
401	`authentication_error`	`model_access_denied`	The key or team is not allowed to use the requested model.	Use an allowed model or ask the team owner to review model access.
402	`insufficient_quota`	`insufficient_balance`	The key is suspended because the account has no available balance.	Add funds on the console Billing page; billing-suspended keys reactivate after the balance is restored.
429	`rate_limit_error`	`concurrency_limit_exceeded`	This API key has reached its concurrent-request limit for the model. The request is rejected before it is sent upstream.	Wait for the `Retry-After` interval, reduce concurrent requests, then retry.
429	`budget_exceeded`	`budget_exceeded`	A spending limit set on the Quota page for this key or team has been reached.	Wait for the limit period to reset or ask an Owner or Admin to raise the limit. See API keys.
429	`rate_limit_error`	Absent	An upstream provider rate-limited the request.	Retry with backoff or configure a supported fallback.
500	`internal_server_error`	Absent	An unexpected gateway error or a provider failure hidden by the gateway occurred.	Retry cautiously. If it persists, use the request ID and dashboard logs when contacting support.
503	`server_error`	`service_unavailable`	A model-serving worker or API-key verification service is temporarily unavailable.	Honor `Retry-After` when present, then retry.
503	`budget_unavailable`	`budget_unavailable`	Spending-limit checks are temporarily unavailable, so the request was not sent.	Retry after a short delay.
529	`overloaded_error`	`overloaded`	A supported UltraFast model is overloaded.	Honor `Retry-After` and retry after the indicated interval.

Messages endpoint errors#

POST /v1/messages follows the Anthropic error envelope, not the OpenAI error object:

JSON

{
  "type": "error",
  "error": {
    "type": "overloaded_error",
    "message": "The service is temporarily unavailable. Please try again later."
  }
}

Messages errors do not include OpenAI code or param fields. Their type and HTTP status use the Messages-specific mapping, so the same failure can have a different status or type than an OpenAI-compatible endpoint. See the Messages reference.

Common Messages statuses and types#

HTTP status	`error.type`	`error.code`	Meaning	What to do
400	`invalid_request_error`	Absent	The request body or parameters are invalid.	Fix the request before retrying.
401	`authentication_error`	Absent	The API key is missing or invalid.	Check the key and use `Authorization: Bearer <key>` or, only for Messages, `x-api-key` without an `Authorization` header.
402	`invalid_request_error`	Absent	The API key is suspended because the account has no available balance.	Add funds; billing-suspended keys reactivate after the balance is restored.
403	`permission_error`	Absent	The request is not permitted.	Check access with the team owner.
404	`not_found_error`	Absent	The requested model or resource was not found.	Check the model ID and route.
429	`rate_limit_error`	Absent	A provider rate limit or per-key concurrency limit was reached.	Honor `Retry-After` when present; reduce concurrent requests or retry with backoff.
500	`api_error`	Absent	An internal or unclassified error occurred.	Retry cautiously; contact support if it persists.
503	`overloaded_error`	Absent	The Messages service is temporarily unavailable.	Honor `Retry-After` when present, then retry.
503	`api_error`	Absent	The model-serving worker is unavailable.	Retry after the service recovers; honor `Retry-After` when present.
504	`api_error`	Absent	The upstream request timed out.	Retry after a short delay.
529	`overloaded_error`	Absent	A supported UltraFast model is overloaded.	Honor `Retry-After` and retry after the indicated interval.

These are mapped Messages errors. A provider passthrough can preserve its upstream status and error body.

Streaming failures#