API: Fehler, Status-Codes & Limits

Vollständige Referenz der HTTP-Status-Codes, des OpenAI-kompatiblen Fehlerformats, der Budget- und Größenlimits der öffentlichen Kasimir-API.

Die öffentliche Kasimir-API ist OpenAI-kompatibel: Fehler werden im selben JSON-Format wie bei OpenAI zurückgegeben, damit handelsübliche OpenAI-SDKs sie ganz normal als Exception bzw. Fehlerobjekt anzeigen. Dieses Kapitel beschreibt exakt, welche Status-Codes die Endpunkte unter /api/v1/* werfen, was sie bedeuten, wie das Fehlerobjekt aufgebaut ist und welche harten Grenzen (Budget, Payload-Größen) gelten – alles direkt aus dem Quellcode abgeleitet.

Fehlerformat

Alle Fehler der OpenAI-kompatiblen Endpunkte (POST /v1/chat/completions, POST /v1/embeddings, GET /v1/models) werden von server/utils/apiError.ts (toOpenaiError) in das OpenAI-Schema übersetzt:

{
  "error": {
    "message": "Model \"foo\" not found",
    "type": "not_found_error",
    "code": null
  }
}

Der type-Wert wird strikt aus dem Status-Code gemappt:

Status-Codes im Detail

Die folgende Tabelle listet jeden Status-Code, der von der /api/v1/*-Oberfläche geworfen wird, samt auslösender Code-Stelle und Bedeutung.

401 – Authentifizierung

authenticateApiKey (server/utils/apiKeyAuth.ts) wirft 401 in drei Fällen:

• Kein Bearer-Token – message: "Missing bearer token"

• Ungültiger Schlüssel – Hash nicht in company_api_keys gefunden – message: "Invalid API key"

• Widerrufener Schlüssel – revoked_at gesetzt – message: "API key revoked"

Schlüssel haben das Format kasi_<32 Zeichen> und werden nur als SHA-256-Hash gespeichert; der Klartext ist einmalig bei der Erstellung sichtbar.

402 – Budget

assertCompanyBudget (server/utils/apiUsage.ts) prüft vor dem Forwarding an den Upstream:

• companies.monthly_budget_eur ist null oder ≤ 0 → unbegrenzt, kein Limit.

• Andernfalls wird der Monatsverbrauch via company_month_spend_eur ermittelt. Ist used ≥ budget, kommt 402 mit z. B. Monthly budget of €100.00 reached (used €100.42).

403 – Berechtigung

Zwei unabhängige Ursachen:

• Fehlender Scope – authenticateApiKey(event, ['chat:write']) wirft Missing scope: chat:write, wenn dem Schlüssel der nötige Scope fehlt. GET /v1/models erfordert keinen speziellen Scope; chat/completions und embeddings erfordern chat:write.

• Non-EU-Gate – resolveApiModel wirft 403, wenn das Modell eu_hosted = false ist und companies.allow_non_eu_models nicht true ist: Model "…" is not enabled for your organization (non-EU model).

404 – Nicht gefunden

resolveApiModel (Chat/Embeddings) bzw. der Assistant-Handler werfen 404, wenn:

• der Slug in models nicht existiert, inaktiv ist oder eine andere Purpose hat (chat vs. embedding),

• der Slug in companies.disabled_model_slugs steht (wird bewusst als „not found“ getarnt),

• ein Assistant (/v1/assistants/{id}/run) nicht existiert oder einer fremden Firma gehört (Tenant-Isolation),

• das Assistant-Modell nicht existiert/inaktiv ist – Model "…" not found or inactive.

502 / durchgereichte 5xx – Upstream

Antwortet die LiteLLM-Schicht nicht mit 2xx (oder fehlt der Body beim Streaming), wirft Kasimir res.status || 502 mit Upstream error: <erste 200 Zeichen der Upstream-Antwort>. Bei 502 ist die Ursache typischerweise, dass der Upstream gar keinen verwertbaren Status lieferte.

Limits

In Phase 1 gibt es keine Rate-Limits und keine 429-Antworten – pro-Key-Spend-Caps und pro-Key-Rate-Limits sind ausdrücklich auf Phase 2 verschoben. Das einzige durchgesetzte „Mengen“-Limit ist das Firmen-Monatsbudget (siehe 402). Daneben gelten Payload-Schemagrenzen:

Fehlerbehandlung (Empfehlungen)

Da das Fehlerformat OpenAI-konform ist, fängt jedes OpenAI-SDK diese Fälle automatisch ab – z. B. wirft das Python-SDK AuthenticationError (401), PermissionDeniedError (403), NotFoundError (404) und APIStatusError (5xx). Auf error.message lässt sich der konkrete Grund auslesen.