> ## 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.

# Troubleshooting

> Fix the most common problems with requests through the AI Gateway, by the status code or symptom you see.

Start from the status code your application received. The code in the error body narrows it down: [Errors](/api-reference/errors) lists them all. When you ask an admin or support for help, give them the `x-request-id` from the reply.

## 401: the key is not accepted

* **`virtual_key_required`.** No key reached Altrum. Check that your client sends the key and that the base URL points to `https://api.altrum.ai`. Some clients send the key only when it is set in a particular environment variable: see [Coding agents](/ai-gateway/coding-agents).
* **`access_not_found`.** Altrum does not know the key. It may have been revoked, or a character may be missing. Keys start with `sk-alt-`. Ask an admin for a new one, or create one under **AI Gateway**, **My keys**.

## 402: a budget is used up

The message names the budget that ran out and when it resets. A budget can belong to the key, its AI system or the whole organization, and any of them can stop the request. Wait for the reset, or ask an owner or admin to raise it under **Budgets**. See [Budgets and rate limits](/ai-gateway/budgets-and-limits).

## 403: something is not allowed

The code tells you what:

* **`access_blocked`.** The key is switched off or expired.
* **`ai_system_inactive`.** The key belongs to an AI system that is not **Live**: still in draft, waiting for approval, paused or retired. See [Lifecycle](/ai-systems/lifecycle).
* **`model_blocked`.** Either the model is not approved in your [Model catalog](/model-catalog), or the key is limited to other models. The message says which.
* **`provider_blocked`.** Your organization has no credential for that provider, or the key may not use it. See [Provider credentials](/ai-gateway/provider-credentials).
* **`mcp_tool_blocked`.** The key may not use that MCP tool. See [MCP tools](/ai-gateway/mcp).
* **`organization_inactive`** or **`gateway_disabled`.** Your organization is switched off, or its plan does not include the AI Gateway. See [Plans and modules](/plans-and-modules).

## 400, 413 and 422: a guardrail stopped it

* **`guardrail_blocked` (400).** A guardrail stopped the request before it reached the model. The message names the guardrail. Test the same text under **Test guardrails** to see what it found: see [Test guardrails](/guardrails/test).
* **`response_blocked` (422).** The model's reply was stopped. Your request was fine.
* **`payload_too_large` (413).** The request has more text than the guardrails can check at once. Send less, for example by trimming old messages from a long conversation.

If a guardrail stops text it should not, ask whoever owns the AI system's guardrails to adjust it. Do not work around it by switching keys: every key is held to some set of guardrails.

## 429: too many requests

A rate limit on the key, its AI system or the organization was reached, or your organization has too many requests running at once. Retry with backoff: see [Handle errors](/ai-gateway/handle-errors).

## 503: try again

`guardrail_check_failed` means Altrum could not check the request against the guardrails, so it did not send it. This is deliberate: an unchecked request never reaches a model. Retry with backoff, and raise a [support ticket](/support) with the request reference if it keeps happening.

## A model is missing from the model list

[List models](/api-reference/openai/list-models) shows only the models your key may use: approved in your organization, served by a provider you have a credential for, and allowed on the key. Check each of those three.

## A streamed reply arrives all at once

When a guardrail on replies can block or mask, Altrum holds the stream until it has checked the whole reply. This is expected. See [Streaming](/api-reference/streaming).

## Requests do not appear in the request log

Only owners, admins and Governance Leads can open the request log. Every request appears there, but prompts and replies appear only when your organization keeps content. See [Request logs](/ai-gateway/request-logs).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.