Plattform

Fehler

Fehler kommen als JSON im Format des aufgerufenen Endpoints zurück: mit einer verständlichen Meldung und bei Endpoints im OpenAI-Stil zusätzlich mit einem stabilen Code für Programme.

Das Format

Endpoints im OpenAI-Stil
{
  "error": {
    "message": "This API key can't use `gpt-6-astra`. It's limited to gpt-6-sol. Change that at https://zurelay.com/app/keys.",
    "type": "permission_error",
    "param": "model",
    "code": "model_not_allowed"
  }
}

Bei /v1/messages kommen dieselben Fehler im Format von Anthropic zurück. Dieses hat keinen Code: Nutze den HTTP-Status und error.type: { "type": "error", "error": { "type": "...", "message": "..." } }. Jede Chat-, Bild- und Videoantwort hat einen x-request-id-Header, auch bei Fehlern.

Codes

StatusCodeWas du tun kannst
400invalid_requestKorrigiere die Anfrage: Die Meldung sagt, was falsch ist, und param zeigt, wo.
400unsupported_contentDas Modell kann diesen Dateityp nicht lesen. Entferne die Datei oder wähle ein Modell, das ihn unterstützt.
400invalid_urlEin Link in der Anfrage konnte nicht heruntergeladen werden. Die Meldung enthält den zurückgegebenen Status.
400invalid_imageEin Eingabebild konnte nicht verwendet werden (Typ, Größe oder Link).
400image_not_generatedDas Modell hat die Anfrage abgelehnt. Es fallen keine Kosten an.
400context_length_exceededDie Unterhaltung ist für das Modell zu lang. Kürze sie oder wähle ein Modell mit einem größeren Kontextfenster.
400max_tokens_reachedEine nicht gestreamte Antwort von /v1/messages hat max_tokens mitten in einem Tool-Aufruf erreicht und ist daher keine vollständige Nachricht. Die generierte Ausgabe wird berechnet. Sende die Anfrage mit einem höheren max_tokens erneut.
401missing_api_keySende den Schlüssel in Authorization oder x-api-key.
401invalid_api_keyDer Schlüssel ist ungültig oder wurde widerrufen.
401expired_api_keyErstelle einen neuen Schlüssel.
402insufficient_quotaDein Guthaben reicht nach Abzug der für laufende Anfragen reservierten Beträge nicht für diese Anfrage, oder es ist mitten in einer Antwort aufgebraucht. Lade unter Abrechnung Guthaben auf oder fordere mit einem niedrigeren max_tokens weniger Ausgabe an. Wenn die automatische Aufladung bereits läuft, steht das in der Meldung: Versuche es ein paar Sekunden später erneut.
402key_budget_exceededDie Anfrage könnte das Monatsbudget des Schlüssels überschreiten, wenn laufende Anfragen mitgezählt werden, oder hat es mitten in der Antwort erreicht. Erhöhe das Budget oder warte bis zum nächsten Monat.
402key_daily_budget_exceededDasselbe gilt für das Tagesbudget des Schlüssels. Erhöhe es oder warte bis Mitternacht UTC.
403model_not_allowedDer Schlüssel darf dieses Modell nicht verwenden.
403ip_not_allowedDer Schlüssel funktioniert nur von anderen Adressen aus.
404model_not_foundPrüfe die Modell-ID auf der Modellseite.
404unknown_urlDiesen Endpunkt gibt es nicht. Prüfe den Pfad und die Basis-URL.
404video_not_foundIn diesem Workspace gibt es kein Video mit dieser ID.
404image_not_foundIn diesem Workspace gibt es keine Bildanfrage mit dieser ID (GET /v1/images/{id}, für Anfragen mit einer callback_url).
409video_not_readyDas Video ist noch nicht fertig: Frage seinen Status ab, bis er completed ist.
409video_failedDie Videoerstellung ist fehlgeschlagen. Es gibt nichts herunterzuladen. Der Fehler nennt den Grund.
410video_expiredDas Video wurde aus der Bibliothek oder nach 30 Tagen gelöscht.
413too_largeDie Anfrage oder eine Datei überschreitet das Limit. Sende große Dateien als Links.
429rate_limit_exceededWarte retry-after Sekunden und versuche es dann erneut.
429concurrency_limit_exceededIn diesem Workspace laufen bereits 32 Anfragen gleichzeitig. Versuche es nach retry-after Sekunden erneut, sobald eine davon abgeschlossen ist.
500server_errorBei uns ist etwas schiefgelaufen. Versuche es erneut.
502stream_interruptedAls letztes Ereignis eines abgebrochenen Streams gesendet. Was bis zum Abbruch gestreamt wurde, wird berechnet; danach nichts mehr. Versuche es erneut.
503model_unavailableDas Modell ist gerade nicht verfügbar. Versuche es nach retry-after Sekunden erneut oder aktiviere Smart Routing. Wenn retry-after fehlt und x-should-retry: false gesetzt ist, ist das Modell verfügbar, gibt aber für diese Anfrage jedes Mal einen Fehler zurück: Sende sie nicht unverändert erneut.
503server_restartingZurelay startet die Maschine neu, die deine Anfrage bearbeitet hat. Versuche es sofort erneut: Eine andere Maschine übernimmt. Es fallen keine Kosten an, außer wenn bereits ein Stream begonnen hatte. Dann wird berechnet, was bei dir angekommen ist – wie bei einem abgebrochenen Stream.
503storage_unavailableEin Bild wurde erstellt, konnte aber nicht zugestellt werden. Es fallen keine Kosten an; versuche es erneut.
503service_unavailableEin kurzes Problem bei uns. Versuche es erneut.

Erneut versuchen

  • Versuche 429 und 503 erneut. Warte dabei die im Header retry-after angegebene Anzahl an Sekunden (oder verlängere die Wartezeit exponentiell), sofern die Antwort nicht x-should-retry: false meldet.
  • Versuche andere 4xx-Fehler nicht unverändert erneut: Sie schlagen wieder fehl.
  • Fehlgeschlagene Anfragen sind kostenlos. Wiederholte Versuche kosten also nichts, bis einer erfolgreich ist. Bei einem Stream, der mittendrin abbricht, wird berechnet, was er geliefert hat. Im seltenen Fall von 503 mit x-should-retry: false wird die Eingabe berechnet (siehe Abrechnung).
  • Die offiziellen SDKs von OpenAI und Anthropic wiederholen bei den passenden Fehlern bereits automatisch für dich.

Fehler mitten im Stream

Fehler, die ein Modell für deine Anfrage selbst zurückgibt (etwa wegen eines nicht unterstützten Parameters oder einer zu langen Eingabe), kommen mit der eigenen Meldung und dem eigenen Code des Modells als 400 oder 422 zurück.

Fehler mitten im Stream

Sobald ein Stream begonnen hat, kann ein Fehler nicht mehr als HTTP-Status zurückgegeben werden. Stattdessen erhältst du ein abschließendes Fehlerereignis (im Format des Endpunkts), und der Stream endet. Berechnet werden die Eingabe und die Ausgabe, die dich bis dahin erreicht hat – danach nichts mehr. Das ist selten: Die meisten Probleme werden vor dem ersten Token erkannt und durch einen erneuten Versuch behoben.

Ein solches Ereignis beendet auch einen Stream, wenn das Guthaben oder das Budget des Schlüssels mittendrin aufgebraucht ist, mit insufficient_quota, key_budget_exceeded oder key_daily_budget_exceeded. Eine nicht gestreamte Anfrage, bei der das mittendrin passiert, gibt die bis dahin erzeugte Ausgabe zurück – abgeschnitten wie eine Antwort, die max_tokens erreicht hat (finish_reason: "length" oder stop_reason: "max_tokens" bei /v1/messages) – mit einem x-zurelay-stopped-Header, der den Code nennt.

Fragen oder fehlt etwas? Frag unser Support-Team und wir antworten per E-Mail, meist innerhalb einer Minute.