Errors

Error envelope

Every endpoint fails in the same shape:

{
  "error": {
    "code": "invalid_api_key",
    "message": "Invalid API key",
    "request_id": "req_abc123"
  }
}

Field	Description
`code`	Stable machine-readable identifier. Branch on this, not on `message`.
`message`	Human-readable explanation. Wording may change.
`request_id`	Identifies the exact request server-side. Include it when contacting support.

Status and error codes

The codes you will actually see, by status:

Status	Code	Meaning	Retryable
401	`missing_auth`	No `Authorization` header (and no `x-api-key`).	No
401	`invalid_api_key`	The key is not one Anona issued, or was revoked.	No
401	`key_expired`	The key was valid but passed its expiry date. Rotate it.	No
401	`invalid_token`	The dashboard session token is invalid or expired.	No
401	`session_required`	An API key was sent to a session-only (dashboard) endpoint.	No
403	`space_access_denied`	You are not a member of this space.	No
403	`space_read_only`	A read-only member attempted a write.	No
403	`space_owner_only`	A non-owner attempted export, memory delete/patch, or space config.	No
403	`space_unavailable`	The owning org of a shared space has no active API key.	No
403	`insufficient_role`	Your role cannot perform this control-plane action.	No
403	`org_suspended`	The organization is suspended.	No
404	`space_not_found`	The space does not exist, or the id is misspelled.	No
409	`space_ambiguous`	A bare space name matches both your own space and a shared one — use the `qualified_id`.	No
422	`validation_error`	The body fails schema validation. Unknown fields are rejected too, so a misspelled field name lands here rather than being silently dropped.	No
422	`reserved_tag`	A tag starting with the reserved `anona:` prefix.	No
429	`rate_limited`	The per-minute rate ceiling. Clears on its own.	Yes, with backoff
429	`credits_exhausted`	The credit allowance is spent. Backoff will not help — upgrade or wait for the reset.	No
500	`internal_error`	Unexpected server error.	Yes
503	`service_unavailable`	Temporary degradation.	Yes, after a short delay

A handful of framework-level failures (an unmatched route’s 404, for example) fall back to generic codes — bad_request, unauthorized, forbidden, not_found, conflict — but every error a working integration handles carries one of the specific codes above.

Endpoint-specific codes

Status	Code	Where	Meaning
400	`unsupported_model`	`/v1/reason`, proxy endpoints, model settings	`model` is not one this deployment serves. The message lists what is; see model selection.
429	`model_throttled`	`/v1/reason`, proxy endpoints	The chosen model is at capacity. Request limits are per model, so another model may have headroom. Anona never silently substitutes one.
503	`model_unavailable`	`/v1/reason`, proxy endpoints	The model is catalogued but this deployment cannot invoke it. Ours to fix, not yours.
400	`invalid_model`	`/v1/chat/completions`	A model this deployment serves was rejected by the provider itself. Distinct from `unsupported_model`, which is refused before the call is made.
400	`invalid_tunable`	proxy endpoints	An `X-Anona-*` tunable header could not be parsed. The message names the header and what it expected.
401	`key_expired`	any authenticated endpoint	The key was valid but has passed its expiry date. Distinct from `invalid_api_key`: this key worked yesterday, so the fix is to rotate rather than to go looking for the right key. Expiry cannot be extended.
401	`session_required`	every control-plane endpoint — exports, space members, API keys, org, usage, billing, invitations	The endpoint is used by the dashboard and authenticates with a signed-in session, not an API key. The key you sent may be perfectly valid — it is the wrong kind of credential here.
429	`credits_exhausted`	metered endpoints	The monthly credit allowance is spent. Distinct from `rate_limited`, which is a per-minute ceiling and clears on its own.
503	`space_list_unavailable`	`GET /v1/spaces`	Space access could not be determined. Retry; the list is never returned unfiltered.

Some endpoints add further codes. See Documents, Webhooks, Organization, Context Receipts, and Billing.

Common mistakes

# Correct
Authorization: Bearer anona_live_YOUR_KEY

# Also accepted on every data-plane endpoint (how the Anthropic SDK sends keys)
x-api-key: anona_live_YOUR_KEY

# Rejected: the Bearer scheme is missing
Authorization: anona_live_YOUR_KEY

Retrying

Retry 429, 500, and 503 with exponential backoff and jitter. Never retry a 4xx other than 429: the request will fail identically every time.

import time, random

def retry_with_backoff(func, max_retries=3):
    for attempt in range(max_retries):
        try:
            return func()
        except Exception:
            if attempt == max_retries - 1:
                raise
            time.sleep(2 ** attempt + random.uniform(0, 1))

Handling errors in the Python SDK

from anona import AnonaClient, AnonaError

client = AnonaClient(api_key="anona_live_YOUR_KEY")

try:
    results = client.retrieve(space_id="customer-support-bot", query="Where does Alice work?")
except AnonaError as e:
    print(e.status_code, e.detail)

Attribute	Type	Contents
`status_code`	`int`	The HTTP status.
`detail`	`dict` or `str`	The parsed error body, or the raw text when the response is not JSON.

Next steps

API overview

Every endpoint in one table.

Getting Started

API Essentials

Memory (data plane)

LLM Proxy (drop-in)

Account (control plane)

SDKs & MCP

Integrations

Guides

Changelog

Error envelope

Status and error codes

Endpoint-specific codes

Common mistakes

Retrying

Handling errors in the Python SDK

Next steps

API overview

Support

​Error envelope

​Status and error codes

​Endpoint-specific codes

​Common mistakes

​Retrying

​Handling errors in the Python SDK

​Next steps

API overview

Support

Error envelope

Status and error codes

Endpoint-specific codes

Common mistakes

Retrying

Handling errors in the Python SDK

Next steps