Kernleitfäden

Fehler, auf die Agents reagieren können

Verwenden Sie Fehlercodes, Wiederholungszeitpunkte und Modellvorschläge, ohne Prosa analysieren zu müssen

Diese Seite beschreibt maschinenlesbare öffentliche API-Fehler für Anwendungen und Coding-Agents. Sie gewährt keinen Zugriff auf Untersuchungen von Workspace-Anfragen oder Support. Für eine Anfrage in Ihrem Workspace beginnen Sie mit der Anfrage-Fehlerbehebung.

OpenAI-kompatible TokenLab-Fehler können strukturierte Hinweise für einen Agenten oder eine Anwendung enthalten. Verwenden Sie diese Felder, wenn sie vorhanden sind; analysieren Sie nicht die für Menschen lesbare message, um zu entscheiden, was zu tun ist.

Anthropic Messages- und Gemini-APIs behalten ihre nativen Fehlerformate bei, daher gelten die Erweiterungen auf dieser Seite nur für OpenAI-kompatible Chat Completions- und Responses-Fehler.

Optionale Fehlerfelder

Alle unten aufgeführten Felder erscheinen innerhalb des error-Objekts und können fehlen.

FeldTypVerwendung
did_you_meanstringErsatz für ein eingestelltes Modell oder die nächstgelegene verfügbare Modell-ID
suggestionsarrayModelle, die zur Anfrage passen könnten
hintstringEine kurze Erklärung oder vorgeschlagene Aktion
retryablebooleanOb dieselbe Anfrage später erfolgreich sein könnte
retry_afternumberSekunden, die vor einem erneuten Versuch gewartet werden sollten
balance_usdnumberAktuelles Guthaben in USD
estimated_cost_usdnumberGeschätzte Kosten der abgelehnten Anfrage
top_up_urlstringLink zur Abrechnungsseite, bei einigen insufficient_balance-Fehlern
min_top_up_usdnumberMindestaufladung in USD, bei einigen insufficient_balance-Fehlern

Ihr Client sollte dennoch jeden Fehler anhand seines HTTP-Status und code behandeln. Betrachten Sie diese zusätzlichen Felder als nützlichen Kontext, nicht als erforderliche Felder.

Unbekanntes Modell

Ein falsch geschriebenes oder nicht verfügbares Modell gibt 400 model_not_found zurück. Wenn did_you_mean vorhanden ist, zeigen Sie es dem Benutzer an oder führen Sie einen erneuten Versuch nur dann durch, wenn Ihr Produkt bereits die Berechtigung hat, das ausgewählte Modell zu ändern.

{
  "error": {
    "message": "Model not found: please check the model name",
    "type": "invalid_request_error",
    "param": "model",
    "code": "model_not_found",
    "did_you_mean": "gpt-5.6-terra",
    "suggestions": [
      {"id": "gpt-5.6-terra"},
      {"id": "gpt-5.6-luna"}
    ],
    "hint": "Did you mean 'gpt-5.6-terra'? Use GET /v1/models to list all available models."
  }
}

Unzureichendes Guthaben

402 insufficient_balance kann das aktuelle Guthaben und den geschätzten erforderlichen Betrag oder einen Auflade-Link und den Mindestaufladebetrag enthalten. Ihre Anwendung kann einen Auflade-Link, ein kostengünstigeres Modell oder eine kleinere Anfrage anbieten.

{
  "error": {
    "message": "Insufficient balance: this request needs about $0.35 for claude-sonnet-4-6, and your balance is $0.12. Add at least $5 to continue: https://tokenlab.sh/dashboard/billing · Why: https://tokenlab.sh/docs/en/quickstart#why-402 After you top up, your current API key works immediately, no new key needed.",
    "type": "insufficient_balance",
    "code": "insufficient_balance",
    "retryable": false,
    "balance_usd": 0.12,
    "estimated_cost_usd": 0.35,
    "suggestions": [
      {"id": "gpt-5.6-luna"},
      {"id": "deepseek-v4.1-flash"}
    ],
    "hint": "Insufficient balance: need ~$0.350000 for claude-sonnet-4-6, but balance is $0.120000. Try a cheaper model, or top up at https://tokenlab.sh/dashboard/billing."
  }
}

Modell nicht verfügbar

Ein 503 all_channels_failed oder 503 delivery_tier_unavailable bedeutet nicht immer einen vorübergehenden Ausfall. Wenn für den angeforderten Vorgang im ausgewählten Delivery-Tier kein Angebot vorhanden ist, ist retryable auf false gesetzt und retry_after wird weggelassen. Wiederholen Sie dieselbe Anfrage nicht. Überprüfen Sie die Verfügbarkeit des Vorgangs und des Delivery-Tiers mit GET /v1/models, bevor Sie ein anderes Modell auswählen. Ähnliche Namen beweisen keine Verfügbarkeit; nicht verifizierte Alternativen werden weggelassen.

{
  "error": {
    "message": "This model is unavailable for the requested operation and Delivery tier.",
    "type": "all_channels_failed",
    "code": "all_channels_failed",
    "retryable": false,
    "hint": "Check the model's operation and Delivery availability with GET /v1/models. Repeating the same request will not resolve this."
  }
}

Ratenbegrenzung

Warten Sie bei 429 rate_limit_exceeded die Anzahl der Sekunden in retry_after ab oder verwenden Sie den Standard-Antwort-Header Retry-After.

{
  "error": {
    "message": "Rate limit exceeded (1000/min for user role). Please retry later.",
    "type": "rate_limit_exceeded",
    "code": "rate_limit_exceeded",
    "retryable": true,
    "retry_after": 8,
    "hint": "Rate limited. Retry after 8s. Current limit: 1000/min for user role."
  }
}

Kontext zu lang

400 context_length_exceeded wird nicht durch erneutes Senden derselben Anfrage behoben. Kürzen Sie die Eingabe oder lassen Sie den Benutzer ein Modell mit einem größeren Kontextfenster wählen.

{
  "error": {
    "message": "This model's maximum context length is 128000 tokens...",
    "type": "invalid_request_error",
    "code": "context_length_exceeded",
    "retryable": false,
    "suggestions": [
      {"id": "gemini-2.5-pro"},
      {"id": "claude-sonnet-5"}
    ],
    "hint": "Reduce your input or switch to a model with a larger context window."
  }
}

Das richtige API-Format finden

Lesen Sie tokenlab.accepted_request_formats aus GET /v1/models/{model}, bevor Sie eine modellspezifische API verwenden.

WertEndpunkt
openai_chat_completions/v1/chat/completions
openai_responses/v1/responses
anthropic_messages/v1/messages
gemini_generate_content/v1beta/models/{model}:generateContent

Ein akzeptiertes Format bestätigt den Endpunkt. Einzelne Tools und Felder können je nach Modell variieren; überprüfen Sie die Modellseite, bevor Sie sich auf diese verlassen.

Ein Modell nach Aufgabe finden

Die Models API kann eine aktuelle Auswahlliste für Nicht-Chat-Aufgaben zurückgeben:

curl "https://api.tokenlab.sh/v1/models?recommended_for=image"

Gültige recommended_for-Werte sind image, video, music, 3d, tts, stt, embedding, rerank, translation und decision. Senden Sie die gewählte Modell-ID explizit in der Erstellungsanfrage. TokenLab ersetzt sie nicht stillschweigend durch ein anderes Modell.

Maschinenlesbare Übersicht

Agents können eine kompakte API-Übersicht hier lesen:

GET https://api.tokenlab.sh/llms.txt

Sie enthält eine erste Anfrage, gängige Endpunkte, Modellfilter und Anleitungen zur Fehlerbehandlung.

Einen Fehler behandeln, ohne die Anfrage erneut zu senden

Dieses Beispiel führt eine Anfrage aus, behält das ausgewählte Modell bei und meldet strukturierte Wiederherstellungsinformationen. SDK-Wiederholungsversuche sind deaktiviert, damit Ihre Anwendung entscheiden kann, ob ein erneuter Versuch sicher ist. Präsentieren Sie Modellvorschläge für eine explizite Auswahl; wiederholen Sie eine akzeptierte oder zeitlich abgelaufene Generierung nicht automatisch. Um eine zeitlich abgelaufene Anfrage sicher zu wiederholen, senden Sie sie mit einem Idempotency-Key, wie unter Sicher wiederholen mit einem Idempotency-Key beschrieben.

import os
from openai import OpenAI, APIStatusError

with OpenAI(
    api_key=os.environ["TOKENLAB_API_KEY"],
    base_url="https://api.tokenlab.sh/v1",
    timeout=30.0,
    max_retries=0,
) as client:
    try:
        response = client.chat.completions.create(
            model="gpt-5.6-terra",
            messages=[{"role": "user", "content": "Reply only with OK."}],
        )
        print(response.choices[0].message.content)
    except APIStatusError as exc:
        body = exc.body if isinstance(exc.body, dict) else {}
        error = body.get("error", body)
        if not isinstance(error, dict):
            error = {}
        print({
            "status": exc.status_code,
            "request_id": exc.request_id,
            "code": error.get("code"),
            "hint": error.get("hint"),
            "suggested_model": error.get("did_you_mean"),
            "retry_after": exc.response.headers.get("Retry-After") or error.get("retry_after"),
        })
        raise

Auf dieser Seite