Fehler, auf die Agenten reagieren können

Diese Seite behandelt maschinenlesbare Fehler der öffentlichen API für Anwendungen und Coding-Agenten. Sie gewährt keinen Zugriff auf Workspace-Untersuchungen oder Support. Für eigene Anfragen nutzen Sie die Fehlersuche.

OpenAI-kompatible TokenLab-Fehler können strukturierte Hinweise für einen Agenten oder eine Anwendung enthalten. Verwenden Sie diese Felder, wenn sie vorhanden sind; parsen 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 FehlerfelderCopy Anchor Link

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

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

Unbekanntes ModellCopy Anchor Link

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 den Vorgang nur dann erneut aus, 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 https://api.tokenlab.sh/v1/models to list all available models."
  }
}

Unzureichendes GuthabenCopy Anchor Link

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

{
  "error": {
    "message": "Insufficient balance: need ~$0.3500 for claude-sonnet-4-6, but balance is $0.1200.",
    "type": "insufficient_balance",
    "code": "insufficient_balance",
    "balance_usd": 0.12,
    "estimated_cost_usd": 0.35,
    "suggestions": [
      {"id": "gpt-5.6-luna"},
      {"id": "deepseek-v3-2"}
    ],
    "hint": "Try a cheaper model, or top up at https://tokenlab.sh/dashboard/billing."
  }
}

Modell nicht verfügbarCopy Anchor Link

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.

{
  "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."
  }
}

RatenbegrenzungCopy Anchor Link

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

{
  "error": {
    "message": "Rate limit: 1000 rpm exceeded",
    "type": "rate_limit_exceeded",
    "code": "rate_limit_exceeded",
    "retryable": true,
    "retry_after": 8,
    "hint": "Retry after 8s."
  }
}

Kontext zu langCopy Anchor Link

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 findenCopy Anchor Link

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

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.

Modell nach Aufgabe findenCopy Anchor Link

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 und translation. Senden Sie die gewählte Modell-ID explizit in der Erstellungsanfrage. TokenLab ersetzt sie nicht stillschweigend durch ein anderes Modell.

Maschinenlesbare ÜbersichtCopy Anchor Link

Agenten 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.

Fehler behandeln, ohne die Anfrage erneut zu sendenCopy Anchor Link

Das Beispiel sendet genau eine Anfrage, behält das gewählte Modell bei und gibt strukturierte Fehlerinformationen aus. Automatische SDK-Wiederholungen sind deaktiviert. Lassen Sie Modellvorschläge ausdrücklich bestätigen; wiederholen Sie angenommene oder zeitlich abgebrochene Generierungen nicht automatisch.

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