Error catalog

All error responses follow a stable envelope. The same shape is used by both /v1/* and /c1/* endpoints.

{
  "error": {
    "type":    "<category>",
    "code":    "<stable-code>",
    "message": "<human-readable>",
    "param":   "<json-pointer>"
  }
}

• type — the top-level category. Since 2026-08-22 it is a pure function of the HTTP status, using the vocabulary of the Anthropic Messages API (the only reference API that documents its type set normatively — OpenAI's OpenAPI spec declares type: string without an enum). You can therefore derive one from the other, and a 404 always carries not_found_error:

  HTTP	type
  400, 422	invalid_request_error
  401	authentication_error
  403	permission_error
  404	not_found_error
  409	conflict_error
  413	request_too_large
  429	rate_limit_error
  500, 502	api_error
  503	overloaded_error
  504	timeout_error

  Before that date we used our own values (permission_denied, not_found, rate_limit_exceeded, upstream_error, internal_error) and the mapping contradicted itself — six 404s and five 409s carried invalid_request_error. If you branch on type, update those five names. Branching on the HTTP status keeps working unchanged, and that is what the OpenAI and DeepSeek SDKs do.

• code — stable machine-readable identifier. Once published, codes are never repurposed. Adding new codes is non-breaking.

• message — human-readable english.

• param (optional) — JSON-Pointer to the offending field, e.g. messages[0].content[1].image_url.url.

Machine-readable catalog

Pull the full catalog as JSON from GET /errors (no auth):

curl -s https://dgx.spass.fun/errors | jq '.entries[0]'

{
  "code": "missing_authorization",
  "type": "authentication_error",
  "http_status": 401,
  "title": "Authorization header is missing",
  "description": "All `/v1/*` and `/c1/*` endpoints require a Bearer token.",
  "remediation": "Add `Authorization: Bearer <RUST_API_BEARER>` to the request.",
  "typical_param": "headers.authorization"
}

Use this to generate stable error-handling code in your client without hand-typing constants.

Cross-link from JSON to docs

Each entry below has a stable HTML-anchor matching its code. The machine-readable JSON at /errors can be cross-linked into this page via /docs/errors#<code>. Example: a failed call returning {"code":"image_base64_invalid"} jumps to /docs/errors#image_base64_invalid. Anchors do not change once published.

Complete code list

The table below is generated from the catalog at serve time — it cannot fall behind the code. Until 2026-08-22 this page and /errors were maintained by hand and had drifted to 44 and 31 entries respectively, against 51 codes that actually exist; twenty codes that are thrown in production appeared in neither.

The sections after it are hand-written deep dives for the codes that need one — they explain why, the table states what.

Authentication errors (401)

missing_authorization

Add Authorization: Bearer <RUST_API_BEARER> to the request.

invalid_authorization

The Bearer token did not match any token in the multi-tenant catalog. The comparison is constant-time. The same code is also returned when an SPASS-Tenant-Id header is presented that the matched token is not bound to.

Permission denied (403)

forbidden

The bearer is valid, but the operation needs a scope the token does not have. Permissions follow docs/adr/0003-api-key-permissions-model.md: scope-strings (resource:action[:qualifier]) are the source of truth, optional roles seed the default set, and extra_scopes/deny_scopes adjust per token. Grant the needed scope (edit auth/tokens.yaml::tokens[].extra_scopes or assign a richer role, then restart the chat-gateway) or use a token that already has it. The rejection log line names the missing scope.

Rate-limit / Quota (429)

rate_limit_exceeded

Per-token rate limits (default 1 request/sec, 30 burst). Bucket is keyed on SHA-256 of the bearer, not IP.

model_quota_exhausted

Cut 2.23d (2026-05-04). The chosen model is temporarily unavailable for this tenant because some upstream budget — token quota, daily credit limit, or rate window — has been used up. The body is intentionally provider-agnostic per ADR 0006 v2: no upstream-name, no token counts, no billing URLs. Identical caller-facing shape to other rate-limit responses.

Fix options for the caller:

• Pick a different model alias (e.g. swap openai-gpt-latest → anthropic-claude-opus-latest). The cross-vendor fallback chain (router_settings.fallbacks in litellm/config.yaml) tries this automatically before emitting model_quota_exhausted; only if the entire cascade is out you see this code.
• Wait for the budget window. Daily-credit windows typically reset at the start of the next UTC day.

Operator action: raise the per-tenant budget in tokens.yaml if affordable, or top up with the upstream provider directly.

openrouter_daily_quota_exhausted

Cut 2.32 (2026-05-16, CR-0005). Tenant-Alias (z.B. godelmann-gocreate-premium-gpt-text-premium) hat sein OpenRouter-Tageslimit erschöpft. Anders als beim generischen model_quota_exhausted (Cut 2.23d) ist hier der Provider explizit identifiziert weil der Alias direkt openrouter-gepinnt ist (kein cross-vendor-Fallback im Stack-Pfad).

Response-Shape:

HTTP/2 429
Retry-After: 32400
content-type: application/json

{
  "error": {
    "type": "rate_limit_error",
    "code": "openrouter_daily_quota_exhausted",
    "message": "GPT-Tageslimit über OpenRouter erschöpft. Reset um 00:00 UTC. Verfügbare Fallback-Modelle: …"
  },
  "dgx_code": "openrouter_daily_quota_exhausted",
  "available_fallbacks": ["godelmann-gocreate-premium-claude-text-premium", "godelmann-gocreate-premium-gemini-text-premium"]
}

Caller-Pattern: auf dgx_code: "openrouter_daily_quota_exhausted" mappen, dem User "GPT-Tageslimit erreicht, probiere Claude oder Gemini" zeigen, Retry-After für ein Auto-Retry nach Mitternacht UTC nutzen.

Notices on successful responses (HTTP 200)

Some responses are complete but carry a note about how they came about — the tool loop hit its cap, a hallucinated tool call was stripped, a safety fallback was substituted. These are not errors and never appeared in this catalog as such; until 2026-08-22 they travelled as a top-level dgx_code field in the body, which made them a second, parallel code channel next to error.code.

They now travel on the SPASS-Notice response header (non-streaming) and as named spass.* SSE events (streaming). See Response headers for the value list.

Invalid request (4xx)

body_too_large

Bodies cap at MAX_BODY_BYTES (default 32 MB). Most often hit with very large base64 image payloads.

invalid_json

The body could not be parsed as JSON. Validate against /openapi.json.

missing_field

Required field absent. The param field of the error envelope shows which one.

invalid_field

A field's value did not match expected type/range/enum. See param for which field.

model_not_in_allowlist

The model slug isn't whitelisted by the stack. Use one of the slugs from /v1/info or /v1/models.

max_tokens_below_minimum

Some upstream cloud paths reject low values (max_output_tokens >= 16), reasoning models need >= 200 to leave room for hidden reasoning tokens before any visible content. The rust-api silently floors max_tokens to the model's documented minimum and reports the adjustment via response header:

spass-applied: max_tokens_floored=200

Only when even the floor would still be invalid does the error surface. Read the per-model constraints.min_max_tokens from /v1/info:

curl -s -H "Authorization: Bearer $BEARER" https://dgx.spass.fun/v1/info \
  | jq '.models[] | {alias, min_max_tokens: .constraints.min_max_tokens}'

image_url_not_supported

Cloud providers refuse to fetch arbitrary URLs server-side; local inference doesn't either. The rust-api validates against constraints.accepts_image_url before forwarding and rejects up-front so you get a clear param pointer instead of an opaque 400 from the upstream.

Encode your image as a base64 data URI:

B64=$(base64 -w 0 image.jpg)
curl -s -H "Authorization: Bearer $BEARER" \
     -H "Content-Type: application/json" \
     -d "{
       \"model\": \"llama-4-scout\",
       \"messages\": [{
         \"role\": \"user\",
         \"content\": [
           {\"type\": \"text\", \"text\": \"Describe this\"},
           {\"type\": \"image_url\", \"image_url\": {\"url\": \"data:image/jpeg;base64,$B64\"}}
         ]
       }]
     }" \
     https://dgx.spass.fun/v1/chat/completions

image_decode_error

The base64-encoded data URI could not be parsed, the MIME type was missing, or the decoded bytes were not a valid image. Verify format data:image/<jpeg|png|webp|gif>;base64,<data>. Re-encode with base64 -w 0 (no line wrapping).

image_base64_invalid

Pre-flight check: rust-api decodes every data:image/...;base64,<payload> and rejects non-parseable base64 before forwarding upstream. Common JS bug: passing a UTF-8 string through btoa corrupts non-ASCII bytes — read as Uint8Array first. Output must be [A-Za-z0-9+/]+={0,2} only.

tool_call_arguments_invalid

OpenAI's tool-calling spec encodes function.arguments as a JSON-string (e.g. "arguments":"{\"key\":\"value\"}"). rust-api parses each argument-string with serde_json before forwarding upstream — non-parseable JSON is caught here so the caller gets a clear diagnostic instead of an opaque upstream Pydantic validation error. Cockpit-followup-6 (S.5) defense-in-depth Layer 1.

upstream_bad_request

Upstream returned a 4xx (often 400 BadRequest) — typically caused by malformed payloads pre-flight didn't catch (corrupt base64, schema-validation error, content moderation flag). rust-api propagates the upstream status-code 1:1 instead of opaque 502, so the caller can distinguish "client-side-fixable" from "upstream-outage".

embedding_input_too_large

/v1/embeddings enforces two caps to protect the pooling-runner: at most 256 elements in the input array, and at most 8192 bytes (≈ 2k tokens) per element. Both match the embedding service's max-model-len. Split large documents into chunks (typical 512–1024 tokens) and send batches of ≤ 256 inputs.

cloud_consent_required

GoCreate #4. One or more kind:"document" attachments would be sent to a cloud model (leaving local infrastructure) without the user having consented to uploading that specific document. Only enforced for tenants with c1_cloud_doc_consent: true. The body carries dgx_code: "cloud_consent_required" and required_consents: [{content_hash, doc_name}]. Re-send with header SPASS-Cloud-Consent: <content_hash>[;persist][, ...] (one entry per consented document; ;persist stores a permanent grant), or route the documents to a local model.

recursion_depth_exceeded

An /a1/agents/<name>/chat request arrived with the SPASS-Caller-Depth header at or above the configured maximum (3). The handler refuses a further self-call because the request would form an /a1 → /v1 → /a1 chain. In normal operation no caller sets this header — drop it, or find the intermediary/proxy that is propagating it.

Not found (404)

conversation_not_found

The supplied conversation_id was never persisted (or was deleted, or belongs to a different user_id).

route_not_found

Path/method combination does not exist on this server.

Agent, RAG, session & config (/a1 + /v1 sub-resources)

Resource-level codes for the agent (/a1), RAG, session, image, memory, tenant-config, and system-prompt surfaces. All share the same envelope.

agent_not_found

The requested agent name is not in the file-based agent registry (loaded once at process start). List with GET /a1/agents; add a YAML file and restart to create one.

agent_tool_not_registered

An agent's tools[] lists a name the runtime tool-registry does not contain (typo, or a tool renamed/removed since the agent was authored). Fix the agent.yaml and restart.

index_not_found

The requested RAG index id is not present in the tenant-scoped registry. Indices are created on first POST /a1/rag/indices/<id>/documents. List with GET /a1/rag/indices.

document_not_found

The index exists for this tenant, but the requested document id is absent. List with GET /a1/rag/indices/<id>/documents.

session_not_found

The requested session id is not in the tenant-scoped session-store. List with GET /a1/agents/<name>/sessions or create a fresh one.

session_agent_mismatch

Sessions are pinned to the agent_name they were created with; the path's <name> differs. Address the session under its original agent, or start a new one under the desired agent.

session_compact_conflict

Either the session has too few live messages to compact (≤ compact_keep_last_n), or it is already archived (read-only). For archived sessions, follow the successor_session_id in the lineage view.

image_not_found

Generated images are stored per-tenant with a default 12 h TTL (up to 7 days via ttl_hours). 404 means the id is wrong, the image belongs to a different tenant, or the TTL lapsed. List with GET /v1/images.

memory_bucket_full

Each (scope_id, visibility, owner) bucket has a 16 KB cap (sum of LENGTH(key)+LENGTH(value)). Delete/shorten entries via DELETE /v1/memory or the memory_forget tool; GET /v1/memory/usage shows utilisation.

memory_confirm_required

Public-memory writes through the LLM tool path require an explicit second tool-call with a confirm_token (60 s TTL) — defense against prompt-injection that flips a private write to public. Re-invoke memory_remember with the same arguments plus the token. REST writes (POST /v1/memory) do not need this.

tenant_config_key_readonly

PUT /v1/tenant/config accepts only Group C (UX/Operational) keys per ADR 0013. The requested key is Group B (security/billing/permissions) — those live in tokens.yaml and require an operator yaml-edit + restart.

tenant_config_invalid_value

The value is out of range, wrong type, an unknown enum, or names a model not in the tenant's effective allowlist. See the validation message; inspect allowed ranges via GET /v1/tenant/config.

system_prompt_too_large

Each system-prompt level (tenant/scope/user) has an 8 KB content cap by default (MAX_SYSTEM_PROMPT_BYTES_PER_LEVEL). The limit is per-level; three levels stack to ≈ 24 KB.

system_prompt_version_not_found

The addressed (level, scope_id?, user_id?, version) tuple is unknown. List versions via GET /v1/system-prompts/{level}/versions.

system_prompt_current_locked

Hard-delete refuses to remove the version with is_current=1. Roll back to a different version (PUT /v1/system-prompts/{level}/current/{n}) or soft-delete the current one first, then hard-delete.

Upstream (5xx)

upstream_error

A non-recoverable upstream 5xx. The server includes the (sanitised) upstream message inline in message. Common causes: model rejected oversize prompt, content moderation flag, provider-side outage.

upstream_timeout

Hit HTTP_TOTAL_TIMEOUT_SECS (default 600 s). Most often a slow image- generation model (gpt-image regularly 100-180 s). Increase your client timeout; check constraints.typical_response_seconds per model in /v1/info. For gpt-image, set client timeout ≥ 240 s.

upstream_unavailable

Could not establish a TCP/TLS connection to the routing gateway or local inference backend. Check /readyz and docker ps / docker logs.

Internal (500)

Recommended client pattern

import httpx

def call_gateway(payload: dict) -> dict:
    r = httpx.post(
        "https://dgx.spass.fun/v1/chat/completions",
        headers={"Authorization": f"Bearer {BEARER}"},
        json=payload,
        timeout=240,  # cover gpt-image worst case
    )
    if r.is_error:
        body = r.json().get("error", {})
        code = body.get("code", "unknown")
        if code == "rate_limit_exceeded":
            time.sleep(2); return call_gateway(payload)
        if code == "image_url_not_supported":
            # rewrite image_url to base64 and retry
            ...
        raise GatewayError(code, body.get("message"), body.get("param"))
    # honour silent adjustments
    if applied := r.headers.get("spass-applied"):
        log.info("server floored: %s", applied)
    return r.json()