Fehler und Ratenbegrenzungen

Jeder Endpunkt schlägt auf die gleiche Weise fehl, daher behandelst du Fehler, Ratenlimits und Wiederholungsversuche einmal und verwendest diesen Code überall wieder, auch über MCP.

Jede nicht-2xx-Antwort ist ein JSON-Objekt:

{
  "defined": false,
  "code": "TOO_MANY_REQUESTS",
  "message": "Too many requests",
  "data": { "reason": "rate_limit.exceeded", "retryAfterMs": 12000 }
}

• code ist der HTTP-Level-Fehler, zum Beispiel UNAUTHORIZED, FORBIDDEN, NOT_FOUND, BAD_REQUEST oder TOO_MANY_REQUESTS.
• data.reason ist, falls vorhanden, ein genauerer maschinenlesbarer Grund wie auth.key_not_found oder rate_limit.exceeded. Verzweige darauf statt auf message, das für Menschen gedacht ist und sich ändern kann.
• defined ist true, wenn die Operation diesen Fehler in der API-Referenz auflistet, und false für Fehler, die jede Anfrage treffen können (Authentifizierung, Ratenlimits, eine unbekannte Route).
• Eine Validierungsfehlermeldung antwortet mit BAD_REQUEST und den Problemen in data.formErrors und data.fieldErrors.

Jede Antwort enthält außerdem eine X-Request-ID. Gib sie an, wenn du den Support kontaktierst, damit wir diese genaue Anfrage finden können.

Jede Antwort gibt das Limit an, gegen das sie gezählt wurde, in zwei Formen:

• die X-RateLimit-*-Header;
• die IETF-Strukturfelder RateLimit (Live-Zustand: r sind die verbleibenden Anfragen, t die Sekunden bis zum Zurücksetzen des Fensters) und RateLimit-Policy (das Kontingent: q ist das Limit, w das Fenster in Sekunden).

Eine 429 enthält außerdem Retry-After in Sekunden und data.retryAfterMs. Warte mindestens so lange, bevor du die nächste Anfrage sendest; ein früherer Wiederholungsversuch wird gezählt und abgelehnt.

Ein Schreibvorgang, der einen Idempotency-Key-Header in der API-Referenz auflistet, kann wiederholt werden, ohne die Arbeit doppelt auszuführen. Sende einen Schlüssel pro logischem Schreibvorgang und wiederhole denselben Schlüssel bei jedem Wiederholungsversuch:

• derselbe Schlüssel mit demselben Body innerhalb von 24 Stunden gibt die gespeicherte Antwort erneut aus;
• derselbe Schlüssel mit einem anderen Body wird mit 422 abgelehnt;
• ein Duplikat, das ankommt, während der erste Vorgang noch läuft, erhält 409.

Ein Vorgang ohne diesen Header ist nicht idempotent, daher wiederhole ihn nur, wenn du sicher bist, dass der erste Versuch nicht erfolgreich war.