Kernleitfäden
API-Fehler behandeln
Fehlercodes lesen, nur bei Bedarf wiederholen und die Request ID speichern
Behandeln Sie Fehler anhand des HTTP-Status und des code. Die message ist für Menschen geschrieben und kann sich ohne Vorankündigung ändern.
Chat Completions und Responses verwenden ein error-Objekt im OpenAI-Stil. Anthropic Messages und Gemini verwenden ihre eigenen Fehlerformate; verwenden Sie daher nicht denselben Parser für jede TokenLab API.
{
"error": {
"message": "Human-readable description",
"type": "error_type",
"code": "error_code",
"param": "parameter_name",
"retryable": true,
"retry_after": 30
}
}Nur message und type sind in OpenAI-kompatiblen Fehlern, die von TokenLab erstellt wurden, immer vorhanden. Andere Felder erscheinen, wenn sie relevant sind.
Statuscodes
| Status | Bedeutung | Typische Maßnahme |
|---|---|---|
400 | Ein Feld, eine Modell-ID oder eine Eingabe ist ungültig | Anfrage korrigieren; nicht unverändert wiederholen |
401 | API-Key fehlt, ist ungültig, abgelaufen oder wurde widerrufen | Key ersetzen |
402 | Guthaben oder API-Key-Limit ist zu niedrig | Aufladen, Limit erhöhen oder Anfrage reduzieren |
403 | Dieser Key kann die Ressource oder das Modell nicht verwenden | Berechtigungen des Keys oder Modell ändern |
404 | Ressource existiert nicht oder ist nicht mehr verfügbar | ID und den API-Key, der sie erstellt hat, überprüfen |
413 | Anfrage oder hochgeladene Datei ist zu groß | Eingabe auf das dokumentierte Modell- oder Endpunkt-Limit reduzieren |
429 | Anfrage-Limit erreicht | Auf Retry-After warten |
500–504 | Dienst nicht verfügbar oder Netzwerkfehler | Nur bei retryable: true wiederholen; retry_after und ein Versuchslimit beachten |
Häufige Fehlercodes
| Code | Bedeutung | Was zu ändern ist |
|---|---|---|
invalid_api_key | Der API-Schlüssel fehlt, ist ungültig, inaktiv oder widerrufen | Authorization-Header und Key-Wert überprüfen |
expired_api_key | Der API-Schlüssel ist abgelaufen | Aktiven Key erstellen oder auswählen |
insufficient_balance | Das Kontoguthaben deckt die Anfrage nicht ab | Guthaben aufladen, Anfrage reduzieren oder günstigeres Modell wählen |
quota_exceeded | Der API-Key hat sein eigenes Limit erreicht | Limit des Keys erhöhen oder anderen autorisierten Key verwenden |
model_not_allowed | Der Key kann das angeforderte Modell nicht verwenden | Modellliste des Keys aktualisieren oder erlaubtes Modell wählen |
model_not_found | Die Modell-ID ist unbekannt oder nicht verfügbar | /v1/models lesen und eine aktuelle Modell-ID verwenden |
context_length_exceeded | Eingabe ist länger, als das Modell akzeptiert | Verlauf entfernen oder Modell mit größerem Kontextfenster wählen |
rate_limit_exceeded | Zu viele Anfragen im aktuellen Zeitfenster gesendet | Auf Retry-After warten |
payload_too_large | Request-Body oder Datei überschreitet das Endpunkt-Limit | Eingabe reduzieren oder komprimieren |
all_channels_failed | Das gewählte Modell kann diese Anfrage nicht bedienen | Nur bei retryable: true wiederholen; retry_after und ein Versuchslimit beachten |
timeout_error | Die Anfrage wurde nicht rechtzeitig abgeschlossen | Nur wiederholen, wenn der Vorgang sicher wiederholt werden kann |
503 all_channels_failed oder 503 delivery_tier_unavailable bedeutet nicht immer einen vorübergehenden Ausfall. Gibt es für die angeforderte Operation im gewählten Delivery-Tarif kein Angebot, ist retryable gleich false und retry_after fehlt. Wiederholen Sie die Anfrage nicht unverändert. Prüfen Sie Operation und Delivery-Verfügbarkeit mit GET /v1/models, bevor Sie ein anderes Modell wählen. Ähnliche Namen belegen keine Verfügbarkeit; ungeprüfte Alternativen werden nicht aufgeführt.
Einige OpenAI-kompatible Fehler enthalten optionale Felder wie did_you_mean, suggestions, alternatives, hint, retryable oder retry_after. Siehe Fehler, auf die Agenten reagieren können.
Wenn eine Anfrage über eine Official-Route lief und der Upstream-Dienst die Anfrage selbst abgelehnt hat, etwa wegen einer nicht akzeptierten Eingabe oder einer Content-Policy-Entscheidung, enthält der Fehler zusätzlich upstream: die message des Upstreams im Originalwortlaut sowie code und source (Name des Upstream-Dienstes), sofern bekannt. Fehler von Anthropic Messages und Gemini enthalten dasselbe Objekt in ihrem eigenen error. Verzweigen Sie weiterhin nach code und type; Werte von upstream.code legt der Upstream-Dienst fest und sie können sich ändern.
Entscheidungen zur Wiederholung (Retry)
| Fehler | Dieselbe Anfrage wiederholen? |
|---|---|
400, 401, 402, 403, 404, 413 | Nein. Ändern Sie die Anfrage, Anmeldedaten, das Guthaben, Berechtigungen oder die Eingabe. |
429 | Ja, nach der vom Server bereitgestellten Verzögerung. |
500–504 | Nur bei retryable: true wiederholen; retry_after und ein Versuchslimit beachten |
| Verbindung vor Antwort geschlossen | Manchmal. Überprüfen Sie bei Erstellungsoperationen, ob bereits eine Aufgabe oder ein Seiteneffekt existiert. |
| Stream nach Ausgabe unterbrochen | Nicht als vollständige Antwort werten. Eine Wiederholung kann eine andere Ausgabe oder eine zweite Abrechnung verursachen. |
Speichern Sie bei der Erstellung von Bildern, Videos, Musik, 3D-Inhalten und Welten die Task-ID, sobald sie zurückgegeben wird. Wenn eine Erstellungsanfrage ein Timeout hat, überprüfen Sie den Aufgabenverlauf, bevor Sie eine weitere Erstellungsanfrage senden.
Die Request ID beibehalten
Antwort-Header enthalten eine Request ID zur Nachverfolgung. Speichern Sie diese zusammen mit dem Endpunkt, dem Modell, der Zeit und Ihrer eigenen Benutzer- oder Job-ID. Speichern Sie bei asynchronen Arbeiten auch task_id und billing_transaction_id, sofern vorhanden.
Wenn Sie den Support kontaktieren, fügen Sie diese IDs und ein redigiertes Beispiel bei. Senden Sie niemals API-Keys, Management-Token, private Medien, signierte URLs oder vollständige private Prompts.