Fehler & Antworten

Jeder öffentliche API-Endpoint gibt vorhersehbare Antwortformen zurück. Fehler tragen einen stabilen maschinenlesbaren Code im Körper, sodass Sie darauf verzweigen können, ohne Englisch zu parsen.

Antwortumschlag

Erfolgreiche Antworten geben die Ressource (oder eine Liste von Ressourcen) direkt zurück. Es gibt keinen Top-Level-Wrapper — Clients können direkt in ein typisiertes Modell deserialisieren:

GET /api/public/v1/org

{
  "id": "e188fc87-…",
  "name": "Acme Corp",
  "plan": "growth",
  …
}

Fehlerantworten verwenden eine kleine einheitliche Form mit einem error-Code als einzigem erforderlichem Feld. Optionale Felder geben Kontext, der Ihnen hilft, den Aufruf zu beheben:

{
  "error": "insufficient_scope",
  "required": "assignments:write",
  "present": ["assignments:read", "users:read"]
}

Statuscode-Referenz

Status	Wann Sie es sehen	Was zu tun ist
`200`	Anfrage erfolgreich. Körper enthält die Ressource oder eine Bestätigungsnachricht.	Verarbeiten Sie den Körper.
`400`	Fehlerhafte Anfrage: fehlendes Pflichtfeld, ungültiger Enum-Wert, Körper zu groß, nicht parsbares JSON.	Beheben Sie die Client-Anfrage — wiederholen Sie nicht dieselbe Payload.
`401`	Fehlendes, fehlerhaftes, widerrufenes oder abgelaufenes Token.	Überprüfen Sie den `Authorization`-Header. Rotieren Sie das Token, wenn es widerrufen wurde.
`403`	Token ist gültig, aber es fehlt der erforderliche Scope.	Fügen Sie den Scope in der Administrator-UI hinzu; die Antwort enthält den genauen Scope-Namen.
`404`	Ressource existiert nicht oder gehört einer anderen Organisation.	Holen Sie die übergeordnete Sammlung erneut ab. Folgen Sie keinen veralteten IDs über Organisationen hinweg.
`409`	Konflikt — z.B. eine E-Mail wird bereits verwendet.	Als Erfolg behandeln, wenn Ihre Operation idempotent ist.
`413`	Anfragekörper überschreitet die Pro-Endpoint-Obergrenze. Wird von Kestrel für harten Überlauf zurückgegeben; der SARIF-Endpoint gibt dies auch als `400 body_too_large` zurück, wenn der deklarierte `Content-Length` 10 MB überschreitet.	Kürzen Sie die Payload. Für SARIF nehmen Sie die Befunde eines Tools schrittweise auf.
`429`	Rate Limit auf diesem API-Schlüssel erreicht.	Berücksichtigen Sie `Retry-After`; siehe Rate Limits.
`5xx`	Serverseitiges Problem.	Wiederholen Sie mit exponentiellem Backoff. Erfassen Sie den Antwort-`X-Request-Id`-Header und zitieren Sie ihn in jedem Support-Ticket.

Fehlercodes

Das error-Feld ist über Versionen stabil — verzweigen Sie im Client-Code darauf statt auf den HTTP-Status, da derselbe Status verschiedene Codes tragen kann:

Code	Status	Bedeutung
`unauthorized`	401	Kein nutzbares Bearer-Token in der Anfrage.
`insufficient_scope`	403	Token ist in Ordnung, Scope fehlt. Die Antwort enthält `required` und `present`.
`rate_limited`	429	Obergrenze überschritten. Siehe `Retry-After`-Header.
`user_not_found`	404	Benutzer-ID existiert nicht oder ist nicht in Ihrer Organisation.
`team_not_found`	404	Team-ID existiert nicht oder ist nicht in Ihrer Organisation.
`assignment_not_found`	404	Zuweisungs-ID existiert nicht oder ist nicht in Ihrer Organisation.
`empty_body`	400	POST oder PATCH ohne Körper gesendet, wo einer erforderlich ist.
`body_too_large`	400 / 413	Anfragekörper überschritt die Endpoint-Obergrenze. SARIF gibt dies als 400 mit `maxBytes` im Körper aus, wenn der deklarierte `Content-Length` zu groß ist; Kestrel gibt einen blanken 413 aus, wenn der Körper tatsächlich überläuft.

Request-IDs

Jede Antwort trägt einen X-Request-Id-Header (UUID v4). Erfassen Sie ihn clientseitig und schließen Sie ihn in Support-Anfragen ein — er ermöglicht es uns, den genauen serverseitigen Trace für den fehlschlagenden Aufruf zu ziehen. Für 5xx-Antworten ist die Request-ID der einzige schnellste Weg zur Diagnose.

Validierungsfehler

Validierungsfehler bei POST- und PATCH-Körpern geben 400 mit einem flachen error zurück, der die erste fehlschlagende Regel beschreibt. Multi-Field-Validierungs-Aufzeigung ist nicht Teil von v1 — beheben Sie das erste gemeldete Feld und wiederholen Sie. Zukünftige Versionen können Detail pro Feld hinzufügen; der Top-Level-error-Vertrag bleibt bestehen.

Auf Fehler verzweigen — Beispiel

const res = await fetch(url, { headers });
if (res.ok) return res.json();

const body = await res.json().catch(() => ({}));
switch (body.error) {
  case 'rate_limited':
    return retryWithBackoff(url);
  case 'insufficient_scope':
    throw new Error(`API key missing scope: ${body.required}`);
  case 'unauthorized':
    throw new Error('API key revoked or invalid — rotate the secret');
  default:
    throw new Error(`API error ${res.status}: ${body.error || 'unknown'}`);
}