Fehler & Wiederholungen

Fehler werden als JSON mit einem stabilen, maschinenlesbaren error-Code und dem passenden HTTP-Status zurückgegeben.

{
  "error": "rate_limited",
  "message": "Too many requests.",
  "retry_after_ms": 850
}

Fehlercodes

HTTP	`error`	Wiederholen?	Hinweise
400	`invalid_request`	Nein	Ein Parameter ist bei der Validierung durchgefallen — korrigiere die Anfrage.
401	`missing_api_key` / `unknown_api_key`	Nein	Siehe Authentifizierung.
403	`inactive_api_key` / `account_blocked`	Nein	Key deaktiviert oder Konto gesperrt.
402	`insufficient_credits`	Nein	Aufladen. Der Body enthält `required` und `balance`.
429	`rate_limited`	Ja, nach `retry_after_ms`	Du hast dein Limit pro Minute überschritten.
409	`request_in_progress`	Ja	Eine identische idempotente Anfrage läuft noch.
422	(Idempotenz-Konflikt)	Nein	Ein `Idempotency-Key` wurde mit einem anderen Body wiederverwendet.
503	`service_temporarily_unavailable` / `too_many_concurrent_requests`	Ja, mit Backoff	Vorübergehendes Kapazitätslimit.
504	`result_timeout`	Ja	Der Upstream-Abruf hat `deadline_ms` überschritten.

Wiederhole 429 / 503 / 504 / 409 mit exponentiellem Backoff. Wenn retry_after_ms vorhanden ist, warte mindestens so lange, bevor du es erneut versuchst.
Wiederhole niemals 400 / 401 / 402 / 403 — die Anfrage wird nicht erfolgreich sein, bis du sie änderst.
Die offiziellen SDKs wiederholen vorübergehende Fehler bereits für dich (standardmäßig 2 Wiederholungen) und stellen ein retryable-Flag am Fehler bereit.