API

Error-Codes

Standardisierte Error-Codes, Retry-Logik, Trace-IDs.

Alle Anirag-API-Fehler folgen einem einheitlichen Schema.

Error-Schema

json{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit of 100 queries/min exceeded for API key ar_live_a1b2.",
    "retry_after_ms": 12000,
    "trace_id": "tr_01HKQR..."
  }
}

Jeder Fehler enthält:

→code — Maschinen-lesbarer Code (siehe Liste unten).
→message — Lesbare Fehlerbeschreibung.
→retry_after_ms — Empfehlung für Retry-Wait (nur bei retryable Errors).
→trace_id — Eindeutiger Identifier für Anfragen-Korrelation. Bei Support-Tickets bitte mitliefern.

HTTP-Statuscodes

Status	Bedeutung
400	Bad Request — Validation-Fehler, prüfen Sie Pflicht-Felder.
401	Unauthorized — API-Key fehlt oder ungültig.
403	Forbidden — keine Berechtigung für die Ressource.
404	Not Found — Ressource existiert nicht oder ist gelöscht.
409	Conflict — z. B. Workspace-Name bereits vergeben.
422	Unprocessable Entity — Format korrekt, Inhalt ungültig.
429	Too Many Requests — Rate-Limit. Retry-After beachten.
500	Internal Server Error — Anirag-seitiger Fehler.
502	Bad Gateway — LLM-Provider-Outage. Auto-Failover läuft.
503	Service Unavailable — Wartung. Status-Page beachten.
504	Gateway Timeout — LLM-Provider zu langsam.

Error-Codes (Auszug)

Authentication

→auth_token_missing (401)
→auth_token_invalid (401)
→auth_token_expired (401)
→auth_scope_insufficient (403)

Validation

→validation_failed (400)
→validation_query_too_long (400) — Query > 8.000 Zeichen.
→validation_workspace_not_found (404)

Rate-Limiting

→rate_limit_exceeded (429)
→quota_exceeded (429) — Monats-Quota erreicht. Plan-Upgrade nötig.

LLM-Provider

→llm_provider_unavailable (502) — Failover läuft, Retry empfohlen.
→llm_context_too_long (422) — Anfrage + Kontext > Modell-Limit.
→llm_filter_triggered (422) — LLM-Provider-Content-Filter hat geantwortet.

Storage

→document_too_large (413) — Datei > 50 MB.
→document_format_unsupported (422)
→storage_quota_exceeded (429)

Retry-Logik

Empfohlene Retry-Logik für Clients:

typescriptasync function withRetry<T>(fn: () => Promise<T>, maxAttempts = 3): Promise<T> {
  let lastErr: unknown;
  for (let i = 0; i < maxAttempts; i++) {
    try {
      return await fn();
    } catch (e: any) {
      lastErr = e;
      const code = e?.response?.data?.error?.code;
      const retryable = ["rate_limit_exceeded", "llm_provider_unavailable"].includes(code);
      if (!retryable || i === maxAttempts - 1) throw e;
      const waitMs = e?.response?.data?.error?.retry_after_ms ?? 1000 * 2 ** i;
      await new Promise((r) => setTimeout(r, waitMs));
    }
  }
  throw lastErr;
}

Die offiziellen SDKs implementieren das automatisch.