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.
| Feld | Typ | Verwendung |
|---|---|---|
did_you_mean | string | Ersatz für ein eingestelltes Modell oder die nächstgelegene verfügbare Modell-ID |
suggestions | array | Modelle, die zur Anfrage passen könnten |
hint | string | Eine kurze Erklärung oder vorgeschlagene Aktion |
retryable | boolean | Ob dieselbe Anfrage später erfolgreich sein könnte |
retry_after | number | Sekunden, die vor einem erneuten Versuch gewartet werden sollten |
balance_usd | number | Aktuelles Guthaben in USD |
estimated_cost_usd | number | Geschätzte Kosten der abgelehnten Anfrage |
top_up_url | string | Link zur Abrechnungsseite, bei einigen insufficient_balance-Fehlern |
min_top_up_usd | number | Mindestaufladung 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.
| Wert | Endpunkt |
|---|---|
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.txtSie 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