Kernleitfäden
API-Fehler behandeln
Fehlercodes lesen, nur bei Bedarf wiederholen und die Request ID beibehalten
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 behalten ihre eigenen Fehlerformate bei, 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 Aktion |
|---|---|---|
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, oder das Konto ist eingeschränkt | Berechtigungen des Keys oder Modell ändern, oder Support kontaktieren |
404 | Ressource existiert nicht oder ist nicht mehr verfügbar | ID und den API-Key, der sie erstellt hat, überprüfen |
409 | Der Idempotency-Key wurde bereits verwendet: mit einem anderen Request-Body (idempotency_conflict) oder für eine Anfrage, deren Ergebnis TokenLab nicht zurückgeben kann (idempotency_replay_unavailable, idempotent_response_not_replayable). TokenLab hat die Anfrage nicht erneut ausgeführt | Verwenden Sie einen neuen Key für eine neue Anfrage. Um zu entscheiden, ob Sie mit demselben Key wiederholen sollten, siehe Sicheres Wiederholen mit einem Idempotency-Key |
413 | Anfrage oder hochgeladene Datei ist zu groß | Eingabe auf das dokumentierte Modell- oder Endpunkt-Limit reduzieren |
429 | Request-Limit erreicht | Auf Retry-After warten |
500–504 | Dienst nicht verfügbar oder Netzwerkfehler | Nur wiederholen, wenn retryable auf true steht; retry_after beachten und Versuche begrenzen |
Häufige Fehlercodes
| Code | Bedeutung | Was zu ändern ist |
|---|---|---|
invalid_api_key | Der API-Key fehlt, ist ungültig, inaktiv oder widerrufen | Authorization-Header und Key-Wert überprüfen |
expired_api_key | Der Key ist abgelaufen | Aktiven Key erstellen oder auswählen |
insufficient_balance | Das Kontoguthaben deckt die Anfrage nicht ab | Guthaben hinzufügen, 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 |
user_suspended, account_restricted | HTTP 403. Das Konto kann die API nicht nutzen | Support mit der Request ID kontaktieren |
invalid_delivery_policy | HTTP 400. Der X-TokenLab-Delivery-Policy-Header ist nicht auto, verified oder official | Einen der drei Werte senden oder den Header entfernen |
model_not_found | Die Modell-ID ist unbekannt oder nicht verfügbar | /v1/models lesen und aktuelle Modell-ID verwenden |
context_length_exceeded | Eingabe ist länger als vom Modell akzeptiert | Verlauf entfernen oder Modell mit größerem Kontextfenster wählen |
missing_required_parameter | Ein erforderliches Feld fehlt. param benennt es, zum Beispiel model bei Audio- und Bildanfragen, die kein Standardmodell haben | Das Feld senden, das param benennt |
invalid_value | Ein Feld hat einen Wert, den das Modell nicht akzeptiert, zum Beispiel ein reasoning_effort-Wert. Die Nachricht listet die akzeptierten Werte auf | Einen der aufgelisteten Werte verwenden |
invalid_response_format_type | HTTP 400. response_format ist ein Objekt ohne nutzbares type oder mit einem type, den dieser Endpunkt nicht akzeptiert. param ist response_format | Setzen Sie response_format.type auf text, json_object oder json_schema; bei json_schema senden Sie zusätzlich json_schema.name und json_schema.schema |
invalid_image_url | TokenLab kann eine Bild-URL nicht verwenden: sie ist keine gültige HTTP(S)-URL oder Bild-Daten-URI, oder der Bild-Host hat das Bild nicht zurückgegeben. param benennt das Feld | Öffentliche HTTPS-Bild-URL oder unterstützte Daten-URI senden |
unsupported_model_capability | Keine Route des gewählten Delivery-Tiers unterstützt einen Anfrageparameter, wie z. B. die Operation, resolution, aspect_ratio, duration, ein Eingabemedienfeld, web_search_options oder max_tokens. Die Nachricht benennt jeden Parameter, der nicht übereinstimmte, und, wenn das Modell sie veröffentlicht, die unterstützten Werte | Parameter entfernen oder ändern, oder anderes Delivery-Tier oder Modell wählen; Anfrage nicht unverändert wiederholen |
unpriceable_selection | Die Videoanfrage lässt einen Selektor aus, von dem der Preis abhängt, daher kann TokenLab ihn nicht bepreisen. param benennt den Selektor | Das Feld setzen, das param benennt |
model_pricing_unavailable | HTTP 503. Die Anfrage ist gültig, aber TokenLab kann diese Kombination aus Modell und Operation auf den Routen, die die Anfrage nutzen kann, nicht bepreisen. Die Anfrage wurde nicht berechnet und retryable ist false | Anfrage nicht unverändert wiederholen; anderes Modell oder andere Operation wählen oder Support mit der Request ID kontaktieren |
idempotency_conflict | HTTP 409. Der Idempotency-Key gehört zu einer anderen Anfrage. TokenLab hat diese Anfrage nicht ausgeführt | Neue Anfrage mit neuem Key senden |
idempotency_replay_unavailable | HTTP 409. Der Idempotency-Key wurde bereits verwendet und TokenLab hat kein Ergebnis dafür zurückzugeben. TokenLab hat diese Anfrage nicht erneut ausgeführt | Wenn die erste Anfrage noch laufen könnte, warten und mit demselben Key wiederholen. Andernfalls neuen Key senden. Siehe Sicheres Wiederholen mit einem Idempotency-Key |
idempotent_response_not_replayable | HTTP 409. Der Idempotency-Key gehört zu einer Erstellungsanfrage, deren Aufgabe bereits abgeschlossen ist, und TokenLab kann die ursprüngliche Erstellungsantwort nicht zurückgeben. Die oberste Ebene des Response-Bodys enthält task_id neben error. TokenLab hat diese Anfrage nicht erneut ausgeführt | Anfrage nicht mit diesem Key wiederholen. Neuen Key nur senden, wenn Sie eine neue Aufgabe wünschen |
rate_limit_exceeded | Zu viele Anfragen wurden im aktuellen Zeitfenster gesendet | Auf Retry-After warten |
all_channels_failed | Das gewählte Modell kann diese Anfrage nicht bedienen | Nur wiederholen, wenn retryable auf true steht; retry_after beachten und Versuche begrenzen |
timeout_error | Die Anfrage wurde nicht rechtzeitig abgeschlossen | Nur wiederholen, wenn die Operation sicher wiederholt werden kann |
Ein 503 all_channels_failed oder 503 delivery_tier_unavailable bedeutet nicht immer einen vorübergehenden Ausfall. Wenn die angeforderte Operation im gewählten Delivery-Tier nicht verfügbar ist, ist retryable false und retry_after wird weggelassen. Wiederholen Sie nicht dieselbe Anfrage. Überprüfen Sie die Verfügbarkeit der Operation und des Delivery-Tiers mit GET /v1/models, bevor Sie ein anderes Modell auswählen. Ähnliche Namen beweisen keine Verfügbarkeit; unverifizierte Alternativen werden weggelassen.
Einige OpenAI-kompatible Fehler enthalten optionale Felder wie did_you_mean, suggestions, alternatives, hint, retryable oder retry_after. Siehe Fehler, auf die Agents reagieren können.
Wenn eine Anfrage auf einer Official-Route lief und der Upstream-Dienst die Anfrage selbst abgelehnt hat, z. B. aufgrund einer Eingabe, die er nicht akzeptiert, oder einer Entscheidung der Content-Richtlinie, enthält der Fehler auch upstream: die message des Upstreams wie gemeldet, plus code und source (der Name des Upstream-Dienstes), sofern bekannt. Anthropic Messages- und Gemini-Fehler enthalten dasselbe Objekt innerhalb ihres eigenen error. Verzweigen Sie weiterhin nach code und type; upstream.code-Werte werden vom Upstream-Dienst definiert und können sich ändern.
Entscheidungen zur Wiederholung
| 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 wiederholen, wenn retryable auf true steht; retry_after beachten und Versuche begrenzen |
| Verbindung vor einer Antwort geschlossen | Ja, wenn die Anfrage in Sicheres Wiederholen mit einem Idempotency-Key aufgeführt ist und einen Idempotency-Key hat: senden Sie sie erneut mit demselben Key und Body. Überprüfen Sie andernfalls zuerst, ob bereits eine Aufgabe oder ein Seiteneffekt existiert. |
| Stream unterbrochen, nachdem Ausgabe eingetroffen ist | Nennen Sie es keine vollständige Antwort. Eine Wiederholung kann eine andere Ausgabe oder eine zweite Berechnung erzeugen. |
Speichern Sie bei der Erstellung von Bildern, Videos, Musik, 3D-Inhalten und Worlds die Aufgaben-ID, sobald sie zurückgegeben wird. Wenn eine Erstellungsanfrage eine Zeitüberschreitung (Timeout) hat, senden Sie sie erneut mit demselben Idempotency-Key und Body, um die ursprüngliche Aufgabe zu erhalten. Überprüfen Sie ohne Key den Aufgabendatensatz, bevor Sie eine weitere Erstellungsanfrage senden.
Sicheres Wiederholen mit einem Idempotency-Key
Ein Timeout oder eine geschlossene Verbindung verrät Ihnen nicht, ob TokenLab die Anfrage ausgeführt hat. Fügen Sie den unten aufgeführten Anfragen einen Idempotency-Key-Header hinzu. Dann kann eine Wiederholung derselben Anfrage diese nicht ein zweites Mal ausführen oder berechnen.
- Verwenden Sie für jede Operation einen neuen eindeutigen Wert, zum Beispiel eine UUID. Ein Key kann bis zu 255 Zeichen lang sein. TokenLab ignoriert einen längeren Key, und die Anfrage hat dann keinen Idempotency-Schutz: eine Wiederholung wird ausgeführt und erneut berechnet.
POST /v1/messages/batchesist anders: es lehnt einen Key, der länger als 256 Zeichen ist, mit400ab. - Speichern Sie den Key in Ihrem eigenen Job-Datensatz, bevor Sie die Anfrage senden.
- Wenn Sie wiederholen, senden Sie denselben API-Key, denselben
Idempotency-Keyund denselben Body. - Verwenden Sie diesen Key nach jeder Antwort außer
409mitidempotency_replay_unavailablenicht erneut. Senden Sie jeden neuen Versuch mit einem neuen Key. - Deaktivieren Sie SDK-Wiederholungen (
max_retries=0), damit Ihr Code entscheidet, wann ein Key wiederverwendet wird.
Ohne den Header ist jede Wiederholung eine neue Anfrage.
Anfragen, die eine Aufgabe erstellen
Diese Erstellungsanfragen akzeptieren Idempotency-Key:
POST /v1/videos/generations,POST /v1/music/generations,POST /v1/3d/generationsundPOST /v1/worlds/generationsPOST /v1/images/generationsundPOST /v1/images/edits, wenn sie eine Aufgabe zurückgebenPOST /v1/responsesmit"background": truePOST /v1/messages/batches
Wenn eine Erstellungsanfrage eine Zeitüberschreitung hat, senden Sie sie unverändert erneut. TokenLab gibt das Ergebnis der ursprünglichen Erstellungsanfrage zurück und erstellt, versendet oder berechnet keine zweite Aufgabe. Normalerweise ist das Ergebnis die ursprüngliche Aufgabe mit derselben id (für Responses das ursprüngliche Antwortobjekt), und Sie fahren fort, diese abzufragen. Bei Video-, Musik-, 3D-, Worlds- und Bildaufgaben kann das Ergebnis auch der ursprüngliche Fehler sein, wenn die erste Erstellungsanfrage fehlgeschlagen ist. Wenn eine solche Aufgabe bereits abgeschlossen ist und TokenLab keine gespeicherte Erstellungsantwort hat, gibt die Wiederholung 409 mit dem Code idempotent_response_not_replayable zurück, und die oberste Ebene des Response-Bodys enthält task_id.
Wenn Sie einen anderen Body mit einem Key senden, den TokenLab bereits akzeptiert hat, lehnt TokenLab die Anfrage ab und erstellt keine Aufgabe. Video-, Musik-, 3D- und Worlds-Erstellungsanfragen geben 409 mit dem Code idempotency_conflict zurück. Message Batches gibt 409 mit dem Fehlertyp conflict_error zurück. Für Bildaufgaben und für Responses-Anfragen mit background: true sind der Statuscode und der Fehlercode für diesen Fall nicht garantiert. Wiederholen Sie die Anfrage nicht mit demselben Key.
Chat Completions, Responses und Messages
POST /v1/chat/completions, POST /v1/responses ohne background und POST /v1/messages führen eine Anfrage mit einem gegebenen Key nur einmal aus. Eine Wiederholung mit demselben Key erhält eines dieser Ergebnisse:
| Situation | Ergebnis |
|---|---|
| Die erste Anfrage läuft noch | 409 mit Code idempotency_replay_unavailable |
| Die erste Anfrage wurde abgeschlossen, nachdem Ihr Client die Verbindung getrennt hat. Die Anfrage wurde nicht gestreamt, das Ergebnis ist 1 MB oder kleiner und Sie wiederholen innerhalb von 24 Stunden mit demselben Body | 200 mit dem ursprünglichen Response-Body und dem Header Idempotent-Replayed: true. TokenLab führt die Anfrage nicht erneut aus und berechnet sie nicht erneut |
| Der Key wurde auf andere Weise verwendet, zum Beispiel: Sie haben das Ergebnis erhalten, die Anfrage wurde gestreamt, das Ergebnis war größer als 1 MB oder es sind mehr als 24 Stunden vergangen | 409 mit Code idempotency_replay_unavailable |
| Der Body unterscheidet sich von der ersten Anfrage | 409, normalerweise mit Code idempotency_conflict. Einige Anfragen geben idempotency_replay_unavailable zurück |
Ein 409 mit einem der beiden Codes bedeutet, dass TokenLab die Anfrage nicht erneut ausgeführt hat. Eine gestreamte Anfrage mit einem Key kann nicht zweimal ausgeführt werden, aber TokenLab kann ihre Ausgabe nicht erneut senden.
Dieses Beispiel wiederholt eine Chat Completions-Anfrage mit Zeitüberschreitung mit demselben Key, bis das Ergebnis vorliegt:
import os
import time
import uuid
import openai
from openai import OpenAI
client = OpenAI(
api_key=os.environ["TOKENLAB_API_KEY"],
base_url="https://api.tokenlab.sh/v1",
timeout=120.0,
max_retries=0,
)
def create_once(messages, model="gpt-5.6-terra", waits=(0, 5, 15, 45)):
key = str(uuid.uuid4()) # Speichern Sie diesen Key in Ihrem Job-Datensatz.
for wait in waits:
time.sleep(wait)
try:
return client.chat.completions.create(
model=model,
messages=messages,
extra_headers={"Idempotency-Key": key},
)
except (openai.APITimeoutError, openai.APIConnectionError):
continue # Keine Antwort: mit demselben Key und Body wiederholen.
except openai.ConflictError as exc:
if exc.code != "idempotency_replay_unavailable":
raise
# Der erste Versuch könnte noch laufen. Eine spätere Wiederholung liefert dessen Ergebnis.
raise RuntimeError(f"Kein Ergebnis für Idempotency-Key {key}")Wenn der letzte Versuch immer noch idempotency_replay_unavailable zurückgibt, kann TokenLab dieses Ergebnis nicht zurückgeben. Senden Sie die Anfrage nur dann mit einem neuen Key, wenn ein zweiter Durchlauf und eine zweite Berechnung akzeptabel sind.
Request ID beibehalten
Response-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 asynchroner Arbeit auch task_id und billing_transaction_id, falls vorhanden.
Wenn Sie den Support kontaktieren, geben Sie diese IDs und ein bereinigtes Beispiel an. Senden Sie niemals API-Keys, Management-Token, private Medien, signierte URLs oder vollständige private Prompts.