# Errori e limiti di frequenza

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

Gli errori arrivano in JSON con un codice `error` stabile e un `message` scritto per una persona:

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

Gestisci i casi in base a `error`, mai a `message`: la formulazione può cambiare.

## Errori HTTP

| Stato | `error` | Significato | Cosa fare |
| --- | --- | --- | --- |
| 400 | `invalid_input` | Il body non è un oggetto JSON con gli argomenti del tool. | Correggi il body della richiesta. |
| 400 | `bad_request` | La richiesta non ha potuto essere letta. | Controlla il JSON e gli header. |
| 401 | `auth_required` | Non è stata inviata alcuna chiave né alcun token. | Invia `Authorization: Bearer <key>`. |
| 401 | `invalid_token` | La chiave o il token non sono validi, sono stati revocati o sono scaduti. | Crea una nuova chiave, oppure lascia che l'agente acceda di nuovo. |
| 401 | `access_revoked` | L'app è stata scollegata dalla dashboard. | Ricollega l'agente. |
| 402 | `balance_required` | Le chiamate gratuite del mese sono esaurite, oppure l'operazione è a pagamento, e il saldo è vuoto. | Aggiungi fondi; la risposta contiene `hint` e `account_url`. |
| 404 | `not_found` | Non esiste un percorso API di questo tipo. | Controlla l'URL. |
| 404 | `unknown_tool` | Nessun tool ha questo nome. | Elenca i tool con `GET /v1/tools`. |
| 405 | `method_not_allowed` | I tool si chiamano con `POST`. | Usa `POST`. |
| 413 | `too_large` | Il body della richiesta è troppo grande. | Invia un file più piccolo o meno elementi. |
| 429 | `rate_limited` | Troppe richieste nell'ultimo minuto. | Attendi i secondi indicati da `Retry-After`, poi riprova. |
| 429 | `daily_limit` | L'account ha raggiunto il suo limite di sicurezza giornaliero. | Riprova il giorno dopo (UTC) o scrivi al supporto. |
| 503 | `unavailable` | Il servizio account non ha risposto. | Riprova dopo i secondi indicati da `Retry-After`. |

## Errori dei tool

Un tool che viene eseguito ma non può rispondere restituisce `200` con `isError: true`. Il suo `structuredContent` contiene allora `code`, `message` e, nella maggior parte dei casi, un `hint` che dice cosa cambiare: un luogo che non ha trovato, un'area troppo grande, un paese che non copre.

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

## Cosa viene conteggiato

Una chiamata che fallisce o non trova nulla non viene conteggiata: la chiamata gratuita o l'importo prelevato dal saldo viene restituito. Contano solo le risposte con un risultato.

## Limiti di frequenza

Ogni account può fare 60 chiamate al minuto. Oltre, l'API risponde `429` con `Retry-After: 60`. Distribuisci nel tempo i job in batch e riprova con un ritardo crescente:

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

Riprova solo `429` e `503`. Un `401` o un `402` non passeranno al secondo tentativo.

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