TokenLab

Guides essentiels

Erreurs sur lesquelles les agents peuvent agir

Utilisez les codes d'erreur, les délais de nouvelle tentative et les suggestions de modèles sans analyser le texte

Cette page décrit les erreurs d'API publique lisibles par machine pour les applications et les agents de codage. Elle n'accorde pas d'accès aux investigations de requêtes d'espace de travail ou au support. Pour une requête dans votre espace de travail, commencez par le dépannage des requêtes.

Les erreurs TokenLab compatibles avec OpenAI peuvent inclure des indices structurés pour un agent ou une application. Utilisez ces champs lorsqu'ils sont présents ; n'analysez pas le message lisible par l'humain pour décider quoi faire.

Les API Anthropic Messages et Gemini conservent leurs formats d'erreur natifs, les extensions sur cette page ne s'appliquent donc qu'aux erreurs de Chat Completions et Responses compatibles avec OpenAI.

Champs d'erreur optionnels

Tous les champs ci-dessous apparaissent à l'intérieur de l'objet error et peuvent être absents.

ChampTypeUtilisation
did_you_meanstringRemplacement pour un modèle retiré, ou l'ID de modèle disponible le plus proche
suggestionsarrayModèles pouvant correspondre à la requête
hintstringUne courte explication ou une action suggérée
retryablebooleanIndique si la même requête peut réussir plus tard
retry_afternumberSecondes à attendre avant de réessayer
balance_usdnumberSolde actuel en USD
estimated_cost_usdnumberCoût estimé de la requête rejetée
top_up_urlstringLien vers la page de facturation, sur certaines erreurs insufficient_balance
min_top_up_usdnumberRechargement minimum en USD, sur certaines erreurs insufficient_balance

Votre client doit toujours gérer chaque erreur par son statut HTTP et son code. Traitez ces champs supplémentaires comme un contexte utile, et non comme des champs obligatoires.

Modèle inconnu

Un modèle mal orthographié ou indisponible renvoie 400 model_not_found. Si did_you_mean est présent, montrez-le à l'utilisateur ou réessayez uniquement lorsque votre produit a déjà l'autorisation de modifier le modèle sélectionné.

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

Solde insuffisant

402 insufficient_balance peut inclure le solde actuel et le montant estimé requis, ou un lien de rechargement et le montant minimum de rechargement. Votre application peut proposer un lien de rechargement, un modèle moins coûteux ou une requête plus petite.

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

Modèle indisponible

Une erreur 503 all_channels_failed ou 503 delivery_tier_unavailable ne signifie pas toujours une panne temporaire. Si l'opération demandée n'a pas d'offre dans le niveau de livraison (Delivery tier) sélectionné, retryable est false et retry_after est omis. Ne répétez pas la même requête. Vérifiez l'opération et la disponibilité de la livraison avec GET /v1/models avant de sélectionner un autre modèle. Des noms similaires ne prouvent pas la disponibilité ; les alternatives non vérifiées sont omises.

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

Limite de débit

Pour 429 rate_limit_exceeded, attendez retry_after secondes ou utilisez l'en-tête de réponse standard 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."
  }
}

Contexte trop long

400 context_length_exceeded ne se résout pas en envoyant à nouveau la même requête. Raccourcissez l'entrée ou laissez l'utilisateur choisir un modèle avec une fenêtre de contexte plus large.

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

Trouver le bon format d'API

Lisez tokenlab.accepted_request_formats depuis GET /v1/models/{model} avant d'utiliser une API spécifique à un modèle.

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

Un format accepté confirme le point de terminaison. Les outils et champs individuels peuvent toujours varier selon le modèle ; vérifiez la page du modèle avant de vous y fier.

Trouver un modèle par tâche

L'API Models peut renvoyer une liste actuelle pour les tâches hors chat :

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

Les valeurs recommended_for valides sont image, video, music, 3d, tts, stt, embedding, rerank, translation et decision. Envoyez l'ID du modèle choisi explicitement dans la requête de création. TokenLab ne le remplace pas silencieusement par un modèle différent.

Aperçu lisible par machine

Les agents peuvent lire un aperçu compact de l'API sur :

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

Il inclut une première requête, des points de terminaison courants, des filtres de modèles et des conseils de gestion des erreurs.

Gérer une erreur sans rejouer la requête

Cet exemple effectue une requête, préserve le modèle sélectionné et rapporte des informations de récupération structurées. Les tentatives automatiques du SDK sont désactivées afin que votre application puisse décider si une nouvelle tentative est sûre. Présentez les suggestions de modèles pour un choix explicite ; ne rejouez pas automatiquement une génération acceptée ou ayant expiré. Pour réessayer une requête ayant expiré en toute sécurité, envoyez-la avec une Idempotency-Key, comme indiqué dans Réessayer en toute sécurité avec une clé d'idempotence.

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

Sur cette page