Aiuto

Errori e limiti di frequenza

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

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

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

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.

Aggiornato il 2026-10-27