Errors

Every refusal on the gateway has the same shape, whichever check refused it, so a client handles one format. The shape is OpenAI’s, so the OpenAI SDKs raise the exception you expect for each status. This page lists every code.

The error object

{
  "error": {
    "message": "tenant is not granted this model",
    "type": "permission_error",
    "code": "model_not_granted",
    "param": null
  }
}

Field	Meaning
`message`	A sentence for a person. Its wording can change; do not parse it.
`type`	The OpenAI category: `authentication_error`, `invalid_request_error`, `permission_error`, `not_found_error`, `insufficient_quota`, `rate_limit_error` or `api_error`.
`code`	The specific reason, from the tables below. Branch on this.

The HTTP status follows from the code, never chosen separately, so the two always agree.

Codes

401: the key itself is unusable

authentication_error. Fix the credential; retrying will not help.

Code	Meaning
`missing_credentials`	No key in `Authorization: Bearer` or `x-api-key`.
`malformed_key`	The value is not shaped like an Olympusx AI key.
`invalid_key`	No such key, or the secret is wrong.
`jwt_unsupported`	A sign-in token was sent. The gateway takes API keys only.
`key_disabled`	The key was revoked.
`key_expired`	The key’s expiry date has passed.
`key_blocked`	The key is blocked.

400 and 422: the request is wrong

invalid_request_error.

Status	Code	Meaning
`400`	`model_required`	The body names no `model`. Send it as a JSON field.
`422`	`guardrails_unscannable`	The guardrails could not read the content at all. The request is refused rather than passed unscanned.

403: the key is fine, and this is not allowed

permission_error. Ask for access; retrying will not help.

Code	Meaning
`model_not_granted`	The tenant is not granted this model. A platform administrator grants it.
`model_not_allowed`	The key has a model allow-list that does not include this model.
`guardrails_blocked`	The tenant’s guardrail policy, in Enforce mode, blocked the prompt or the answer. See Guardrails.
`ide_key_required`	The codebase tools at `/mcp` take a developer key, and this is an application key.
`code_assistant_disabled`	The codebase tools are called with a developer key, and the tenant’s Code Assistant is off.

404: nothing to serve it

Code	Type	Meaning
`model_not_deployed`	`not_found_error`	The tenant may use the model, and no deployment serves it for this tenant. Deploy it, or wait for its deployment to be ready. A gateway that is still starting answers this for every model until it receives its routes.

429: slow down, or wait for the period

Both carry status 429, so an SDK backs off either way. The type says whether waiting a moment will help.

Code	Type	Meaning
`budget_exceeded`	`insufficient_quota`	A token budget on the key, project or tenant is spent for the current day or month. Retrying will not succeed until the period rolls over or the budget is raised.
`model_budget_exceeded`	`insufficient_quota`	The tenant’s budget for this model is spent for the period.
`request_rate_exceeded`	`rate_limit_error`	The tenant’s requests-per-minute limit is reached. `Retry-After` gives the seconds to wait.
`token_rate_exceeded`	`rate_limit_error`	The tenant’s tokens-per-minute limit is reached. `Retry-After` gives the seconds to wait.

502 and 503: the platform’s side

api_error. Retry with backoff.

Status	Code	Meaning
`503`	`backend_error`	The platform could not reach its own records to decide the request.
`503`	`guardrails_unavailable`	The guardrails scanner did not answer, and the platform fails closed. The prompt was fine as far as anyone knows; the scanner was not.
`503`	(no body)	The gateway could not get a decision at all, for example while the control plane restarts.
`502`	`provider_unavailable`	The cloud provider behind an external model could not be reached or failed.

A 500 with type api_error and no code listed here is a defect; report it with the time and the key ID.

Errors that are not the gateway’s

The model’s own errors pass through unchanged, with the status and body the model’s runtime or the cloud provider sent. A prompt longer than the context window, or a parameter the runtime does not accept, is reported this way, usually as 400.
The public assistant chat uses the same object for rate limits and the gateway’s refusals, and a flat {"error": "...", "detail": "..."} for its own checks. See Agents and assistants over the API.
The management API answers with a flat object: {"error": "<code>", "detail": "<sentence>"}. Without a usable token it answers 401 with "error": "unauthorized" and a detail of missing_bearer_token or invalid_token. A refusal by role is 403 with "error": "forbidden", a reason of role (with roles, the roles that may), no_role or platform_only.