Limiti, errori e risoluzione dei problemi

Il server MCP non ha un proprio catalogo di errori: ogni tool inoltra la risposta reale di /public/v1, quindi l’envelope, i codici e i limiti sono esattamente quelli della API pubblica — Errori e Piani e limiti sono il riferimento completo. Questa pagina traduce i casi più comuni in “cosa fare” quando il fallimento compare dentro il tuo client MCP.

Come un client MCP vede un errore della API

Quando un tool fallisce, il tuo client riceve una risposta con isError: true e lo stesso corpo JSON che restituirebbe la API — il campo error è l’unico che dovresti usare per decidere cosa fare, come con la API direttamente:

{
  "error": "PERMISSION_DENIED",
  "message": "You do not have the required permission for this action",
  "request_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
}

Risoluzione dei problemi

Sintomo	Causa probabile	Cosa fare
401, o l’handshake non si completa nemmeno	La tua chiave non esiste, è stata copiata male o è stata revocata — il server rifiuta la connessione prima di elencare qualsiasi tool	Genera una nuova chiave (guida Chiavi API) e aggiorna il blocco di configurazione del tuo client
Vedi solo aymar_status nell’elenco dei tool, nient’altro	Il tuo tenant non è su un piano Pro/Enterprise (aymar_status risponde eligible: false), oppure la tua chiave non ha nessuno scope di lettura	Chiama aymar_status per confermare quale dei due sia — controlla Piani e limiti o la selezione “Personalizza” della tua chiave
Un tool specifico restituisce 403 PERMISSION_DENIED	La tua chiave non ha lo scope esatto richiesto da quel tool (vedi la colonna “Permesso necessario” nel catalogo)	Crea una nuova chiave con quello scope — la selezione di una chiave esistente non può essere ampliata, solo revocata e ricreata
404 leggendo o aggiornando un id specifico	L’id non esiste, o appartiene a un altro account — stessa risposta in entrambi i casi, per progetto	Conferma l’id nella Piattaforma; un 404 non significa mai “esiste ma non hai accesso”, significa “non c’è”
409 WHATSAPP_SESSION_WINDOW_CLOSED inviando un messaggio	Il contatto è su WhatsApp e sono passate più di 24h dal suo ultimo messaggio in entrata	Usa aymar_conversations_start con un template approvato invece di aymar_conversations_send_message
422 VALIDATION_ERROR	L’argomento che hai dato al tool non rispetta il suo schema (tipo, campo richiesto…)	Il message/details dell’errore stesso descrive il campo esatto — il tool valida lo schema OpenAPI prima di chiamare la API
429 RATE_LIMIT_EXCEEDED	Hai superato la quota di richieste al minuto o al giorno della tua chiave	Attendi i secondi indicati da Retry-After nell’errore — vedi i tetti per piano in Piani e limiti
Un tool di scrittura non fa nulla, restituisce solo un riepilogo	Stai vedendo confirmation_required — è il comportamento atteso, non un fallimento	Vedi La conferma sulle scritture
Il server MCP non risponde affatto	Il server MCP, o la API pubblica dietro di esso, non è disponibile	Il server MCP non mette nulla in cache: se la API non risponde, fallisce anche la chiamata al tool — riprova più tardi, oppure scrivi a soporte@aymaragents.com con il request_id se lo hai

Ancora bloccato? Scrivi a soporte@aymaragents.com con il nome del tool, il request_id dell’errore (se presente) e una breve descrizione — non includere mai la tua chiave API completa nel messaggio.