Erreurs sur lesquelles les agents peuvent agir

Cette page décrit les erreurs lisibles par machine de l’API publique pour les applications et agents de programmation. Elle ne donne aucun accès aux investigations ou au support de votre espace de travail. Consultez le dépannage des requêtes.

Les erreurs TokenLab compatibles avec OpenAI peuvent inclure des indications structurées 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 de la marche à suivre.

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

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

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

Un modèle mal orthographié ou indisponible renvoie 400 model_not_found. Si did_you_mean est présent, affichez-le à l'utilisateur ou réessayez uniquement si 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 https://api.tokenlab.sh/v1/models to list all available models."
  }
}

Solde insuffisantCopy Anchor Link

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

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

Modèle indisponibleCopy Anchor Link

503 all_channels_failed ou 503 delivery_tier_unavailable ne signifie pas toujours une panne temporaire. Si aucune offre ne couvre cette opération dans le niveau Delivery choisi, retryable vaut false et retry_after est absent. Ne répétez pas la même requête. Vérifiez la disponibilité de l’opération et du niveau Delivery avec GET /v1/models avant de choisir 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 (Rate limit)Copy Anchor Link

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: 1000 rpm exceeded",
    "type": "rate_limit_exceeded",
    "code": "rate_limit_exceeded",
    "retryable": true,
    "retry_after": 8,
    "hint": "Retry after 8s."
  }
}

Contexte trop longCopy Anchor Link

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'APICopy Anchor Link

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

Un format accepté confirme l'endpoint. Les outils et champs individuels peuvent toujours varier selon le modèle ; consultez la page du modèle avant de vous y fier.

Trouver un modèle par tâcheCopy Anchor Link

L'API Models peut renvoyer une présélection actuelle pour les tâches autres que le chat :

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

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

Aperçu lisible par machineCopy Anchor Link

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, les endpoints courants, les filtres de modèles et des conseils sur la gestion des erreurs.

Traiter une erreur sans renvoyer la requêteCopy Anchor Link

Cet exemple envoie une seule requête, conserve le modèle choisi et expose les informations structurées de l’erreur. Les nouvelles tentatives automatiques du SDK sont désactivées. Faites confirmer tout changement de modèle ; ne renvoyez pas automatiquement une génération acceptée ou ayant dépassé le délai.

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