El servidor MCP **no tiene su propio catálogo de errores**: cada tool reenvía la respuesta real de
`/public/v1`, así que el envelope, los códigos y los límites son exactamente los de la API pública —
**[Errores](/api/errors/)** y **[Planes y límites](/api/plans-and-limits/)** son la referencia completa.
Esta página traduce los casos más comunes a "qué hacer" cuando el fallo aparece dentro de tu cliente MCP.

## Cómo ve un cliente MCP un error de la API

Cuando una tool falla, tu cliente recibe una respuesta con `isError: true` y el mismo cuerpo JSON que
devolvería la API — el campo `error` es el único que deberías usar para decidir qué hacer, igual que con
la API directamente:

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

## Resolución de problemas

| Síntoma | Causa probable | Qué hacer |
| --- | --- | --- |
| **401**, o el handshake ni siquiera completa | Tu clave no existe, está mal copiada o fue revocada — el servidor rechaza la conexión antes de listar ninguna tool | Genera una clave nueva (guía **[Claves de API](/guides/claves-api/)**) y actualiza el bloque de configuración de tu cliente |
| Solo ves **`nuntius_status`** en la lista de tools, nada más | Tu tenant no está en un plan Pro/Enterprise (`nuntius_status` responde `eligible: false`), **o** tu clave no tiene ningún scope de lectura | Llama a `nuntius_status` para confirmar cuál de los dos es — revisa [Planes y límites](/api/plans-and-limits/) o el recorte "Personalizar" de tu clave |
| Una tool concreta da **403 PERMISSION_DENIED** | Tu clave no tiene el scope exacto que exige esa tool (ver la columna "Permiso necesario" del [catálogo](/mcp/tools/)) | Crea una clave nueva con ese scope — el recorte de una clave existente no se puede ampliar, solo revocar y recrear |
| **404** al leer o actualizar un id concreto | El id no existe, o pertenece a otra cuenta — misma respuesta en ambos casos, por diseño | Confirma el id en la Plataforma; un 404 nunca significa "existe pero no tienes acceso", significa "no está" |
| **409 WHATSAPP_SESSION_WINDOW_CLOSED** al enviar un mensaje | El contacto es de WhatsApp y pasaron más de 24h desde su último mensaje entrante | Usa `nuntius_conversations_start` con una plantilla aprobada en vez de `nuntius_conversations_send_message` |
| **422 VALIDATION_ERROR** | El argumento que le diste a la tool no cumple su schema (tipo, campo requerido…) | El propio `message`/`details` del error describe el campo exacto — la tool valida el schema del OpenAPI antes de llamar a la API |
| **429 RATE_LIMIT_EXCEEDED** | Superaste el cupo de peticiones por minuto o por día de tu clave | Espera los segundos que indica `Retry-After` en el error — ver los techos por plan en [Planes y límites](/api/plans-and-limits/) |
| Una tool de escritura no hace nada, solo responde con un resumen | Estás viendo `confirmation_required` — es el comportamiento esperado, no un fallo | Ver **[La confirmación en escrituras](/mcp/confirm/)** |
| El servidor MCP no responde en absoluto | El servidor MCP, o la API pública detrás de él, no está disponible | El servidor MCP no cachea nada: si la API no responde, la tool falla también — reintenta más tarde o escribe a **hola@nuntius.chat** con el `request_id` si lo tienes |

¿Sigue sin resolverse? Escribe a **hola@nuntius.chat** con el nombre de la tool, el `request_id` del
error (si lo hay) y una descripción breve — no incluyas tu clave de API completa en el mensaje.