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](/it/api/errors/)** e **[Piani e limiti](/it/api/plans-and-limits/)** 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:

```json
{
  "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](/it/guides/claves-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](/it/api/plans-and-limits/) 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](/it/mcp/tools/)) | 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](/it/api/plans-and-limits/) |
| 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](/it/mcp/confirm/)** |
| 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.