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

StatusBedeutungTypische Aktion
400Ein Feld, eine Modell-ID oder eine Eingabe ist ungültigAnfrage korrigieren; nicht unverändert wiederholen
401API-Key fehlt, ist ungültig, abgelaufen oder wurde widerrufenKey ersetzen
402Guthaben oder API-Key-Limit ist zu niedrigAufladen, Limit erhöhen oder Anfrage reduzieren
403Dieser Key kann die Ressource oder das Modell nicht verwenden, oder das Konto ist eingeschränktBerechtigungen des Keys oder Modell ändern, oder Support kontaktieren
404Ressource existiert nicht oder ist nicht mehr verfügbarID und den API-Key, der sie erstellt hat, überprüfen
409Der 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ührtVerwenden 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
413Anfrage oder hochgeladene Datei ist zu großEingabe auf das dokumentierte Modell- oder Endpunkt-Limit reduzieren
429Request-Limit erreichtAuf Retry-After warten
500–504Dienst nicht verfügbar oder NetzwerkfehlerNur wiederholen, wenn retryable auf true steht; retry_after beachten und Versuche begrenzen

Häufige Fehlercodes

CodeBedeutungWas zu ändern ist
invalid_api_keyDer API-Key fehlt, ist ungültig, inaktiv oder widerrufenAuthorization-Header und Key-Wert überprüfen
expired_api_keyDer Key ist abgelaufenAktiven Key erstellen oder auswählen
insufficient_balanceDas Kontoguthaben deckt die Anfrage nicht abGuthaben hinzufügen, Anfrage reduzieren oder günstigeres Modell wählen
quota_exceededDer API-Key hat sein eigenes Limit erreichtLimit des Keys erhöhen oder anderen autorisierten Key verwenden
model_not_allowedDer Key kann das angeforderte Modell nicht verwendenModellliste des Keys aktualisieren oder erlaubtes Modell wählen
user_suspended, account_restrictedHTTP 403. Das Konto kann die API nicht nutzenSupport mit der Request ID kontaktieren
invalid_delivery_policyHTTP 400. Der X-TokenLab-Delivery-Policy-Header ist nicht auto, verified oder officialEinen der drei Werte senden oder den Header entfernen
model_not_foundDie Modell-ID ist unbekannt oder nicht verfügbar/v1/models lesen und aktuelle Modell-ID verwenden
context_length_exceededEingabe ist länger als vom Modell akzeptiertVerlauf entfernen oder Modell mit größerem Kontextfenster wählen
missing_required_parameterEin erforderliches Feld fehlt. param benennt es, zum Beispiel model bei Audio- und Bildanfragen, die kein Standardmodell habenDas Feld senden, das param benennt
invalid_valueEin Feld hat einen Wert, den das Modell nicht akzeptiert, zum Beispiel ein reasoning_effort-Wert. Die Nachricht listet die akzeptierten Werte aufEinen der aufgelisteten Werte verwenden
invalid_response_format_typeHTTP 400. response_format ist ein Objekt ohne nutzbares type oder mit einem type, den dieser Endpunkt nicht akzeptiert. param ist response_formatSetzen 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_urlTokenLab 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_capabilityKeine 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 WerteParameter entfernen oder ändern, oder anderes Delivery-Tier oder Modell wählen; Anfrage nicht unverändert wiederholen
unpriceable_selectionDie Videoanfrage lässt einen Selektor aus, von dem der Preis abhängt, daher kann TokenLab ihn nicht bepreisen. param benennt den SelektorDas Feld setzen, das param benennt
model_pricing_unavailableHTTP 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 falseAnfrage nicht unverändert wiederholen; anderes Modell oder andere Operation wählen oder Support mit der Request ID kontaktieren
idempotency_conflictHTTP 409. Der Idempotency-Key gehört zu einer anderen Anfrage. TokenLab hat diese Anfrage nicht ausgeführtNeue Anfrage mit neuem Key senden
idempotency_replay_unavailableHTTP 409. Der Idempotency-Key wurde bereits verwendet und TokenLab hat kein Ergebnis dafür zurückzugeben. TokenLab hat diese Anfrage nicht erneut ausgeführtWenn 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_replayableHTTP 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ührtAnfrage nicht mit diesem Key wiederholen. Neuen Key nur senden, wenn Sie eine neue Aufgabe wünschen
rate_limit_exceededZu viele Anfragen wurden im aktuellen Zeitfenster gesendetAuf Retry-After warten
all_channels_failedDas gewählte Modell kann diese Anfrage nicht bedienenNur wiederholen, wenn retryable auf true steht; retry_after beachten und Versuche begrenzen
timeout_errorDie Anfrage wurde nicht rechtzeitig abgeschlossenNur 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

FehlerDieselbe Anfrage wiederholen?
400, 401, 402, 403, 404, 413Nein. Ändern Sie die Anfrage, Anmeldedaten, das Guthaben, Berechtigungen oder die Eingabe.
429Ja, nach der vom Server bereitgestellten Verzögerung.
500–504Nur wiederholen, wenn retryable auf true steht; retry_after beachten und Versuche begrenzen
Verbindung vor einer Antwort geschlossenJa, 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 istNennen 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/batches ist anders: es lehnt einen Key, der länger als 256 Zeichen ist, mit 400 ab.
  • Speichern Sie den Key in Ihrem eigenen Job-Datensatz, bevor Sie die Anfrage senden.
  • Wenn Sie wiederholen, senden Sie denselben API-Key, denselben Idempotency-Key und denselben Body.
  • Verwenden Sie diesen Key nach jeder Antwort außer 409 mit idempotency_replay_unavailable nicht 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/generations und POST /v1/worlds/generations
  • POST /v1/images/generations und POST /v1/images/edits, wenn sie eine Aufgabe zurückgeben
  • POST /v1/responses mit "background": true
  • POST /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:

SituationErgebnis
Die erste Anfrage läuft noch409 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 Body200 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 vergangen409 mit Code idempotency_replay_unavailable
Der Body unterscheidet sich von der ersten Anfrage409, 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.

Von einer Anfrage zur Untersuchung und zum Support

Auf dieser Seite