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.
| Status | Häufiger Code | Was zu tun ist |
|---|---|---|
400 | validation_error, model_required | Korrigiere die Anfrage. error.param nennt das Feld. |
401 | unauthorised | Prüfe den Schlüssel und den Header Authorization. |
402 | insufficient_funds | Lade Credits auf oder nutze phaseo/free. |
403 | guardrail_blocked | Ändere die Anfrage oder die Guardrail. |
404 | not_found | Prüfe Pfad und ID. |
410 | model_retired | Wechsle zu replacement_model. |
429 | rate_limit_exceeded, key_limit_exceeded | Warte auf Retry-After und versuche es dann erneut. |
5xx | upstream_error, gateway_error | Wiederhole 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 anzeigenAntwort ausblenden
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
error.code und Status, behebe 4xx-Fehler und wiederhole nur 429 und sichere 5xx-Fehler mit Backoff.Weiterführende Links
Zuletzt geprüft am 17. November 2026