Error-Codes

Vollständige Liste aller Anirag-Error-Codes, Bedeutungen und empfohlene Reaktionen.

Alle Anirag-Error-Responses haben dieses Format:

{
  "error": {
    "code": "AUTH_INVALID_KEY",
    "message": "API-Key wurde widerrufen oder existiert nicht.",
    "trace_id": "trc_8f3a2b1c",
    "documentation_url": "https://anirag.io/docs/errors#auth_invalid_key"
  }
}

trace_id immer im Support-Ticket mitsenden.

Auth-Errors

Code	HTTP	Bedeutung & Reaktion
`AUTH_MISSING_TOKEN`	401	Authorization-Header fehlt komplett. Bearer-Token-Format prüfen.
`AUTH_INVALID_KEY`	401	API-Key existiert nicht oder wurde widerrufen. Im Web-UI neuen Key erstellen.
`AUTH_KEY_REVOKED`	401	API-Key wurde aktiv widerrufen. Audit-Log prüfen, wer das gemacht hat.
`AUTH_WORKSPACE_MISMATCH`	403	Key hat Zugriff auf andere Workspaces, aber nicht auf den angefragten.
`AUTH_PLAN_FEATURE_LOCKED`	403	Feature gehört zu höherem Plan (z. B. BYOK ist Business+). Plan upgraden oder Feature weglassen.

Validation-Errors

Code	HTTP	Bedeutung & Reaktion
`VALIDATION_REQUIRED_FIELD`	400	Pflichtfeld fehlt im Body. `error.message` nennt das Feld.
`VALIDATION_INVALID_TYPE`	400	Feld hat falschen Typ (z. B. string statt int). `error.message` zeigt erwarteten Typ.
`VALIDATION_OUT_OF_RANGE`	400	Numerischer Wert außerhalb des erlaubten Bereichs (z. B. `top_k > 20`).
`VALIDATION_INVALID_ID`	400	ID-Format passt nicht zum Prefix (z. B. `ws_` statt `col_`).

Rate-Limit-Errors

Code	HTTP	Bedeutung & Reaktion
`RATE_LIMIT_REQUESTS`	429	Pro-Minute-Limit überschritten. `Retry-After`-Header beachten (Sekunden).
`RATE_LIMIT_QUERIES_MONTH`	429	Monats-Query-Limit überschritten. Plan upgraden oder Overage akzeptieren.
`RATE_LIMIT_EMBEDDINGS_MONTH`	429	Monats-Embedding-Limit überschritten.
`RATE_LIMIT_STORAGE_GB`	429	Storage-Quota überschritten. Alte Documents löschen oder Plan upgraden.

Provider-Errors

Code	HTTP	Bedeutung & Reaktion
`LLM_PROVIDER_UNAVAILABLE`	503	Alle LLM-Provider down. Automatischer Failover läuft, retry empfohlen.
`LLM_PROVIDER_RATE_LIMIT`	429	Provider hat unsere Quota erschöpft. Failover läuft auf nächsten Provider.
`LLM_PROVIDER_INVALID_BYOK`	401	BYOK-Key (Anthropic, OpenAI, ...) ist ungültig. Bei Provider rotieren.
`LLM_PROVIDER_CONTENT_POLICY`	400	LLM-Provider hat den Prompt aufgrund seiner Content-Policy abgelehnt.

Document-Indexing-Errors

Code	HTTP	Bedeutung & Reaktion
`DOC_FILE_TOO_LARGE`	413	Datei > 100 MB. Splitting empfohlen oder Plan-Upgrade.
`DOC_UNSUPPORTED_FORMAT`	400	Nicht-unterstütztes Format. Erlaubt: pdf, docx, md, txt, html, url.
`DOC_PARSE_FAILED`	422	PDF konnte nicht geparst werden (verschlüsselt, korrupt, etc.). `error.message` hat Details.
`DOC_OCR_FAILED`	422	Scan-PDF: OCR fehlgeschlagen. Häufig bei sehr alten Scans (unter 200 dpi).

System-Errors

Code	HTTP	Bedeutung & Reaktion
`SYSTEM_INTERNAL`	500	Unerwarteter Fehler. `trace_id` im Support-Ticket aufbewahren.
`SYSTEM_DEGRADED`	503	System läuft im Degraded-Mode (z. B. Cache aus). Status-Page checken.
`SYSTEM_MAINTENANCE`	503	Geplante Wartung. `Retry-After`-Header beachten.