Errors

Every error is JSON with a stable code you can switch on. The status tells you whether to retry; the code tells you why it happened; the message is for a human.

Envelope#

error

{
  "error": {
    "message": "Model \"openai/gpt-9\" is not allowed for this API key",
    "type": "invalid_request_error",
    "code": "model_not_allowed",
    "request_id": "9550cc20-5c1f-45e1-8413-08874b3f1a64"
  }
}

request_id matches the X-Ahura-Request-Id header and the usage record. Errors from the Anthropic-compatible route use Anthropic’s envelope instead, with the same status codes.

Codes#

Status	Code	Cause	What to do
400	`invalid_json`	The body is not valid JSON.	Fix the request.
400	`invalid_request`	A field failed validation; the message names it.	Fix the request.
400	`model_required`	No model, and no preset that supplies one.	Send a model id.
400	`preset_not_found`	X-Ahura-Preset names a preset your organization does not have.	Check the name in the dashboard.
400	`guardrail_blocked`	The guardrail was set to block and a critical pattern matched.	Review the prompt; see Guardrails.
400	`self_serve_model`	A private adapter that is not being served anywhere.	Start a serving pod for it from the dashboard.
401	`invalid_api_key`	Missing, malformed, unknown, revoked or expired key, or a request from outside the key's IP allowlist.	Check the key and where you are calling from.
402	`hard_cap_reached`	This key's monthly hard cap is spent.	Raise the cap on the API keys page, or use another key.
402	`org_hard_cap_reached`	The organization's monthly hard cap is spent.	Raise the cap under Inference settings, or wait for the new month.
403	`model_not_allowed`	The key's model allowlist does not include this model.	Use an allowed model or widen the allowlist.
404	`model_not_found`	Not a catalog id.	Check `GET /v1/models`.
429	`rate_limit_exceeded`	Over the key's requests per minute.	Wait `Retry-After` seconds. The SDKs do this.
429	`upstream_rate_limited`	The model's backend is throttling.	Retry with backoff, or switch model.
503	`model_unavailable`	The model is in the catalog but switched off, or its routing could not be read.	Retry later or use another model.
503	`instance_warming_up`	A hosted model's replicas are all starting.	Wait `Retry-After` seconds and retry.
503	`embeddings_unavailable`	The embeddings endpoint has no provider configured.	Not retryable at present.
502 / 503	`upstream_unavailable`	The model's backend rejected our credentials or is down.	Retry with backoff; we are alerted.
400 / 422	`upstream_rejected_request`	The backend refused the request on a rule of its own.	Read the message; usually a parameter the model does not accept.
500	`internal_error`	A fault inside the gateway.	Retry once; if it persists, contact support with the `request_id`.

Retry 429, 502, 503 and 500 with exponential backoff, honouring Retry-After when present. Never retry 400, 401, 402, 403 or 404: the same request will fail the same way until something on your side changes.

Something missing or wrong on this page? Tell us, and quote the page title.

Envelope#

Codes#

Retry policy#