Lektion 3 von 4 · 8 Minuten

Wenn eine Anfrage fehlschlägt

Verzweige nach Fehlercode und Status und wiederhole nur die Fehler, die später gelingen können.

Jeder Phaseo-Fehler hat auf jedem Endpunkt denselben JSON-Body. Das Objekt error hat die Form, die OpenAI-kompatible SDKs schon lesen:

{
  "error": {
    "code": "insufficient_funds",
    "message": "...",
    "type": "insufficient_quota",
    "param": null
  },
  "generation_id": "G-...",
  "status_code": 402
}

Verzweige nach error.code und dem HTTP-Status, nie nach dem Meldungstext. Protokolliere immer generation_id.

StatusHäufiger CodeWas zu tun ist
400validation_error, model_requiredKorrigiere die Anfrage. error.param nennt das Feld.
401unauthorisedPrüfe den Schlüssel und den Header Authorization.
402insufficient_fundsLade Credits auf oder nutze phaseo/free.
403guardrail_blockedÄndere die Anfrage oder die Guardrail.
404not_foundPrüfe Pfad und ID.
410model_retiredWechsle zu replacement_model.
429rate_limit_exceeded, key_limit_exceededWarte auf Retry-After und versuche es dann erneut.
5xxupstream_error, gateway_errorWiederhole mit Backoff.

Wiederhole 4xx-Fehler außer 429 nicht unverändert: Sie schlagen erneut fehl. Bei 429 wartest du auf Retry-After (Sekunden oder ein HTTP-Datum) oder nutzt exponentielles Backoff mit Jitter. Ein key_limit_exceeded ohne Retry-After setzt sich nicht von selbst zurück, also wiederhole ihn nicht. Wiederhole 5xx nur, wenn ein erneuter Aufruf sicher ist, und setze eine Obergrenze für Versuche und eine Gesamtfrist.

Prüfe dein Verständnis

Deine Anfrage gibt 401 mit dem Code unauthorised zurück. Was sollte dein Code tun?

Wende es an

Ein Batch-Skript sendet 500 Anfragen in einer Schleife. Nach der Hälfte kommen Antworten als 429 mit dem Header Retry-After: 20 zurück. Was änderst du?

Antwort anzeigen

Lass das Skript Retry-After beachten: Es wartet etwa 20 Sekunden, bevor es erneut versucht, und nutzt exponentielles Backoff mit Jitter, wenn der Header fehlt. Prüfe auch error.code: rate_limit_exceeded setzt sich zurück, ein key_limit_exceeded ohne Retry-After aber nicht, Wiederholen ist dann also sinnlos.

Das Wichtigste

Verzweige nach error.code und Status, behebe 4xx-Fehler und wiederhole nur 429 und sichere 5xx-Fehler mit Backoff.

Weiterführende Links

Dein Fortschritt wird in diesem Browser gespeichert.

Zuletzt geprüft am 17. November 2026