Docs

Errors

Every error from /v1/* uses the same envelope as the OpenAI API, so existing error-handling code keeps working unchanged.

Error shape

{
  "error": {
    "message": "string, human-readable",
    "type": "invalid_request_error",
    "param": "model" // or null,
    "code": "model_not_found" // or null
  }
}

Error types

Type	HTTP status	Meaning
invalid_request_error	400	Malformed JSON, or a required parameter is missing (e.g. `model`, `messages`).
authentication_error	401	Missing, malformed, or invalid API key.
not_found_error	404	The `model` id doesn't exist, or the route itself doesn't exist.
rate_limit_error	429	A per-minute, per-day, or per-model limit was reached — see Rate Limits. Also used when the upstream provider itself is rate limiting us.
api_error	502 / 503	The model is temporarily unavailable, or the upstream provider returned an error or an empty response.

Common cases

Unknown model

404 Not Found

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

Missing a required field

400 Bad Request

{
  "error": {
    "message": "you must provide a 'messages' parameter",
    "type": "invalid_request_error",
    "param": "messages",
    "code": null
  }
}

Retrying

429 and 502/503 are generally safe to retry — respect the Retry-After header when present, and back off exponentially.
400, 401, and 404 won't succeed on retry without changing the request itself (fix the body, the key, or the model id).