Aide

Erreurs et limites de débit

Les erreurs arrivent en JSON avec un code error stable et un message écrit pour une personne :

{ "error": "auth_required", "message": "This tool needs a TerraLab account. Connect TerraLab in your assistant's settings; see https://terra-lab.ai/mcp." }

Appuyez-vous sur error, jamais sur message : la formulation peut changer.

Erreurs HTTP

Statut	`error`	Signification	Que faire
400	`invalid_input`	Le corps n'est pas un objet JSON d'arguments d'outil.	Corrigez le corps de la requête.
400	`bad_request`	La requête n'a pas pu être lue.	Vérifiez le JSON et les en-têtes.
401	`auth_required`	Aucune clé ni aucun token n'a été envoyé.	Envoyez `Authorization: Bearer <key>`.
401	`invalid_token`	La clé ou le token est invalide, révoqué ou expiré.	Créez une nouvelle clé, ou laissez l'agent se reconnecter.
401	`access_revoked`	L'application a été déconnectée depuis le tableau de bord.	Reconnectez l'agent.
402	`balance_required`	Les appels gratuits du mois sont épuisés, ou l'opération est payante, et le solde est vide.	Ajoutez des fonds ; la réponse contient `hint` et `account_url`.
404	`not_found`	Ce chemin d'API n'existe pas.	Vérifiez l'URL.
404	`unknown_tool`	Aucun outil ne porte ce nom.	Listez les outils avec `GET /v1/tools`.
405	`method_not_allowed`	Les outils s'appellent avec `POST`.	Utilisez `POST`.
413	`too_large`	Le corps de la requête est trop volumineux.	Envoyez un fichier plus petit ou moins d'objets.
429	`rate_limited`	Trop de requêtes dans la dernière minute.	Attendez `Retry-After` secondes, puis réessayez.
429	`daily_limit`	Le compte a atteint son plafond de sécurité quotidien.	Réessayez le lendemain (UTC) ou écrivez au support.
503	`unavailable`	Le service de compte n'a pas répondu.	Réessayez après `Retry-After` secondes.

Erreurs d'outil

Un outil qui s'exécute mais ne peut pas répondre renvoie 200 avec isError: true. Son structuredContent contient alors code, message et, la plupart du temps, un hint qui dit quoi changer : un lieu introuvable, une zone trop grande, un pays qu'il ne couvre pas.

{
  "structuredContent": { "code": "...", "message": "...", "hint": "..." },
  "content": [{ "type": "text", "text": "..." }],
  "isError": true
}

Ce qui est compté

Un appel qui échoue ou ne trouve rien n'est pas compté : l'appel gratuit ou le montant prélevé sur le solde est restitué. Seules les réponses avec un résultat comptent.

Limites de débit

Chaque compte peut faire 60 appels par minute. Au-delà, l'API répond 429 avec Retry-After: 60. Étalez les traitements par lots dans le temps, et réessayez avec un délai croissant :

import time
import requests

def call(url, headers, body, attempts=5):
    for attempt in range(attempts):
        response = requests.post(url, headers=headers, json=body, timeout=120)
        if response.status_code not in (429, 503):
            return response
        time.sleep(int(response.headers.get("Retry-After", 2 ** attempt)))
    return response

Ne réessayez que les 429 et 503. Un 401 ou un 402 ne passera pas au second essai.

Mis à jour le 2026-10-27