# Erreurs et limites de débit

> Index of the TerraLab docs for agents: [llms.txt](https://terra-lab.ai/docs/llms.txt). Every docs page is also served as markdown: add .md to its URL.

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

```json
{ "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.

```json
{
  "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 :

```python
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.

Source: https://terra-lab.ai/fr/docs/errors · Updated 2026-10-27