Límites, errores y resolución de problemas

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 y Planes y límites 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:

{
  "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) y actualiza el bloque de configuración de tu cliente
Solo ves aymar_status en la lista de tools, nada más	Tu tenant no está en un plan Pro/Enterprise (aymar_status responde eligible: false), o tu clave no tiene ningún scope de lectura	Llama a aymar_status para confirmar cuál de los dos es — revisa Planes y límites 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)	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 aymar_conversations_start con una plantilla aprobada en vez de aymar_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
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
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 soporte@aymaragents.com con el request_id si lo tienes

¿Sigue sin resolverse? Escribe a soporte@aymaragents.com 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.