Skip to main content
Start from the status code your application received. The code in the error body narrows it down: 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.
  • 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.

​
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.
  • model_blocked. Either the model is not approved in your 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.
  • mcp_tool_blocked. The key may not use that MCP tool. See MCP tools.
  • organization_inactive or gateway_disabled. Your organization is switched off, or its plan does not include the AI Gateway. See 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.
  • 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.

​
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 with the request reference if it keeps happening.

​
A model is missing from the model list

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.

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