> ## Documentation Index > Fetch the complete documentation index at: https://dev-docs.altrum.ai/llms.txt > Use this file to discover all available pages before exploring further. # Errors > Every error the AI Gateway returns: the body shape for each format, the status codes, the refusal codes and what to do about each. When Altrum refuses a request or cannot complete it, the error comes back in the format of the API you called. Your SDK raises it as it raises any other error from that API. Every error also carries the request reference in the `x-request-id` header. For code that retries and recovers, see [Handle errors](/ai-gateway/handle-errors). ## Error bodies Each body holds a code you can branch on. The codes stay the same between releases; the messages may be reworded. The refusal code is in `type` and `error.type`. `error.code` holds the refusal code or, for an error without one, a broader code from the status (see [Broad codes](#broad-codes)). ```json theme={null} { "type": "budget_exceeded", "is_gateway_error": true, "status_code": 402, "error": { "type": "budget_exceeded", "code": "budget_exceeded", "message": "Budget exceeded: ..." }, "request_id": "8b0f6c1e-3a4d-4c55-9a51-2f1f0b7c9d10" } ``` The refusal code is in `error.type`. ```json theme={null} { "type": "error", "error": { "type": "model_blocked", "message": "Model 'claude-opus-4' is not allowed" }, "request_id": "8b0f6c1e-3a4d-4c55-9a51-2f1f0b7c9d10" } ``` The refusal code is in `error.status`. The request reference is only in the `x-request-id` header. ```json theme={null} { "error": { "code": 429, "message": "Rate limit exceeded: ...", "status": "rate_limited" } } ``` ## Refusal codes ### Keys and access | Status | Code | Message | What to do | | - | - | - | - | | 401 | `virtual_key_required` | `virtual key is required. Send it as Authorization: Bearer sk-alt-..., or in the x-api-key or x-alt-vk header.` | Send your key. See [Authentication](/api-reference/authentication). | | 401 | `access_not_found` | `access not found. The provided credential does not exist or has been revoked.` | Check the key your application sends. It may have been revoked. | | 403 | `access_blocked` | `virtual key is inactive` or `virtual key has expired` | Ask an admin to switch the key on, or create a new one. | | 401, 403 | `policy_access_denied` | Your own provider key was sent without a virtual key, or your organization does not allow it. | See [Send your own provider key](/api-reference/authentication#send-your-own-provider-key). | ### Organization and AI system | Status | Code | Message | What to do | | - | - | - | - | | 403 | `organization_inactive` | `this organization is inactive. Contact your Altrum administrator to reactivate it.` | Your organization is switched off. Contact [support](/support). | | 403 | `gateway_disabled` | `the AI Gateway is not enabled for this organization. Contact your Altrum administrator.` | Your plan does not include the AI Gateway. See [Plans and modules](/plans-and-modules). | | 403 | `ai_system_inactive` | `this AI system is not live. An owner, an admin, a Governance Lead or the AI system's owner can take it live in Altrum.` | The key belongs to an AI system that is not **Live**. Get it approved and take it live, or resume it. See [Lifecycle](/ai-systems/lifecycle). | ### Models, providers and tools | Status | Code | Message | What to do | | - | - | - | - | | 403 | `model_blocked` | `The model is not approved for this organization. An owner or a Governance Lead can approve it in the Model catalog in Altrum.` | Use an approved model, or ask for it to be approved in the [Model catalog](/model-catalog). | | 403 | `model_blocked` | `Model '' is not allowed`, then the key that refused it | The key may not use this model. Ask an admin to allow it on the key. | | 403 | `provider_blocked` | `Provider '' is not allowed`, then the key that refused it | The key may not use this provider. | | 403 | `provider_blocked` | `Your organization has no credential for . Add one under AI Gateway, Provider credentials, or name another provider.` | See [Provider credentials](/ai-gateway/provider-credentials). | | 400 | | `could not auto resolve a provider for the request, please specify a provider explicitly` | Name the provider in the model, such as `openai/gpt-4o-mini`. | | 403 | `mcp_tool_blocked` | `MCP tools not allowed: ...` | The key may not use this tool. See [MCP tools](/ai-gateway/mcp). | ### Budgets and limits | Status | Code | Message | What to do | | - | - | - | - | | 402 | `budget_exceeded` | `Budget exceeded: ...`, naming the budget, what was spent and when it resets | Wait for the reset, or ask an admin to raise the budget. Retrying sooner will not help. | | 429 | `rate_limited`, `request_limited`, `token_limited` | `Rate limit exceeded: ...`, naming the limit | Wait, then retry with backoff. | | 429 | `organization_concurrency_limit` | `Your organization already has 200 requests running. Wait for one to finish and try again.` | Retry with backoff. | See [Budgets and rate limits](/ai-gateway/budgets-and-limits). ### Guardrails A guardrail error names the guardrails that fired, never your text, and says whose guardrails they were: "this AI system" or "this organization". Fallbacks are not tried after a guardrail refusal. | Status | Code | Message | What to do | | - | - | - | - | | 400 | `guardrail_blocked` | `A guardrail on this AI system stopped the request (). Remove or change the flagged content and send it again.` | Change the request. It was not sent to the model. | | 422 | `response_blocked` | `A guardrail on this AI system stopped the reply (). Your request was fine: change it, or ask for something different.` | Ask for something different. | | 503 | `guardrail_check_failed` | `Altrum could not check this request against the guardrails on this AI system, so it was not sent to the provider. Try again in a moment, and contact support if it keeps happening.` | Retry with backoff. Nothing reached the model. | | 413 | `payload_too_large` | `This request has more text than can be checked against the guardrails (more than 50 parts). Send less text at once.` | Split the request. | When a guardrail would have to change the structured arguments of a tool call, the request or reply is stopped instead, because those cannot be masked safely. See [Guardrails at runtime](/guardrails/at-runtime). ### Prompts | Status | Code | Message | | - | - | - | | 404 | `prompt_not_found` | `No prompt matches the x-alt-prompt-id and x-alt-prompt-version you sent. Check the id and version in your AI Gateway prompts, or remove the headers.` | | 400 | `invalid_prompt_version` | `The x-alt-prompt-version header must be a whole version number, such as 2. Remove it to use the latest version.` | ### When Altrum cannot decide | Status | Code | Message | | - | - | - | | 500 | `access_unresolved` | `could not check whether this organization is active. Try again.` | | 500 | `access_unresolved` | `could not read this organization's approved models. Try again.` | Retry these with backoff, and quote the request reference to [support](/support) if they continue. ## Broad codes An error without a refusal code of its own, such as one from your model provider, gets a broad code from its status in `error.code` on the OpenAI routes: | Status | Code | | - | - | | 400, 413, 422 | `invalid_request` | | 401 | `authentication_failed` | | 402 | `budget_exceeded` | | 403 | `permission_denied` | | 404 | `not_found` | | 429 | `rate_limited` | | 502, 503, 504 | `upstream_unavailable` | | anything else | `internal_error` | An error from your model provider keeps the provider's message, so it reads as it would without Altrum. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.