Errors

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.

Error bodies

Each body holds a code you can branch on. The codes stay the same between releases; the messages may be reworded.

OpenAI
Anthropic
Gemini

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

{
  "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.

{
  "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.

{
  "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.
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.

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

Models, providers and tools

Status	Code	Message	What to do
403	`model_blocked`	`The model <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.
403	`model_blocked`	`Model '<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 '<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 <provider>. Add one under AI Gateway, Provider credentials, or name another provider.`	See 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.

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.

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 (<guardrails>). 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 (<guardrails>). 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.

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

Overview

OpenAI format

Anthropic format

Gemini format

MCP

Error bodies

Refusal codes

Keys and access

Organization and AI system

Models, providers and tools

Budgets and limits

Guardrails

Prompts

When Altrum cannot decide

Broad codes

​Error bodies

​Refusal codes

​Keys and access

​Organization and AI system

​Models, providers and tools

​Budgets and limits

​Guardrails

​Prompts

​When Altrum cannot decide

​Broad codes

Error bodies

Refusal codes

Keys and access

Organization and AI system

Models, providers and tools

Budgets and limits

Guardrails

Prompts

When Altrum cannot decide

Broad codes