Referencia de errores
Códigos de error MCP, qué significan y cómo solucionarlos
Cuando una llamada a herramienta MCP falla, la respuesta incluye isError: true y un objeto de error estructurado. Tu herramienta de IA típicamente explicará el error y sugerirá una solución.
Formato de respuesta de error
{
"error": {
"code": "rate_limited",
"message": "Per-minute unit cap exceeded. Slow down.",
"retryable": true,
"retry_after": 12,
"request_id": "01968a3b-..."
}
}Algunos errores incluyen campos adicionales:
action_url-- un enlace a la página del dashboard de Atribu donde puedes solucionar el problemaworkspaces-- una lista de workspaces disponibles (paraworkspace_required)profiles-- una lista de perfiles disponibles (paraprofile_required)support_hint-- una sugerencia para contactar soporte con elrequest_id
Códigos de error
Fallas de autenticación
Las fallas de autenticación no devuelven un error estructurado de herramienta. Un token faltante, malformado, revocado o expirado recibe una respuesta HTTP 401 con un error JSON-RPC (code: -32001, mensaje "Unauthorized: invalid or missing token") y un header WWW-Authenticate. No hay señal distinta entre expirado y revocado.
Solución: verifica que la solicitud lleve Authorization: Bearer atb_user_.... Si el token fue revocado (o rotado hace más de 48 horas), crea uno nuevo desde Developer > MCP Tokens.
Errores de scope
| Código | Reintentable | Causa | Solución |
|---|---|---|---|
workspace_required | No | El usuario tiene múltiples workspaces y ninguno fue especificado | Pasa workspace_id -- el error incluye una lista de tus workspaces |
profile_required | No | El workspace tiene múltiples perfiles y ninguno fue especificado | Pasa profile_id -- el error incluye una lista de perfiles |
insufficient_scope | No | El token no tiene el scope requerido para esta herramienta | Crea un nuevo token con el scope necesario |
Inferencia de recurso único
Si tienes exactamente un workspace o un perfil, se selecciona automáticamente. Estos errores solo ocurren cuando hay múltiples opciones.
Errores de límite de uso
| Código | Reintentable | Causa | Solución |
|---|---|---|---|
rate_limited | Sí | Límite de unidades por minuto o por período excedido | Espera retry_after segundos, luego reintenta |
El campo retry_after indica cuántos segundos esperar. Las herramientas de IA que soportan reintento lo manejarán automáticamente.
Errores de conector
| Código | Reintentable | Causa | Solución |
|---|---|---|---|
connector_expired | No | El token OAuth de una integración requerida expiró | Re-autoriza en el action_url de la respuesta de error |
connector_required | No | Una integración requerida no está conectada | Conéctala en el action_url de la respuesta de error |
Estos errores incluyen un action_url que enlaza directamente a la página de integraciones en tu dashboard de Atribu.
Errores de write-back
| Código | Reintentable | Causa | Solución |
|---|---|---|---|
writeback_disabled | No | El administrador del workspace no ha habilitado MCP write-back | Pide a un administrador que lo habilite en Settings > Privacy & MCP |
circuit_open | No | 3+ fallas consecutivas en los últimos 30 minutos | Espera al enfriamiento, luego investiga las fallas subyacentes |
Repetir una clave de idempotencia no es un error
Repetir un confirm con una clave de idempotencia ya procesada devuelve una respuesta exitosa con replayed: true y el resultado anterior — sin envío duplicado, sin error.
Errores de entrada
| Código | Reintentable | Causa | Solución |
|---|---|---|---|
invalid_input | No | Parámetros inválidos o faltantes | Verifica los tipos de parámetros y campos requeridos |
data_unavailable | Sí | No existen datos para la ventana o entidad especificada | Amplía el rango de fechas o verifica que la entidad existe |
Errores de servidor
| Código | Reintentable | Causa | Solución |
|---|---|---|---|
internal_error | Sí | Error inesperado del servidor | Reintenta una vez. Si persiste, contacta soporte con el request_id |
Solución de problemas
"Recibo workspace_required pero solo tengo un workspace"
Esto puede pasar si tu token fue creado antes de que un workspace fuera eliminado. Intenta llamar list_workspaces para ver qué workspaces puede acceder tu token, y pasa el workspace_id explícitamente.
"Los datos parecen obsoletos o vacíos"
Revisa el campo meta.data_as_of en las respuestas exitosas. Si tiene más de unas horas, tu integración puede necesitar re-sincronización. Ve a Settings > Integrations y revisa el estado de sincronización.
"No puedo ver los emails de clientes"
El PII se enmascara por defecto. Necesitas las tres cosas: scope mcp:read_pii en el token, include_sensitive: true en la llamada, y modo PII del workspace en full_default. Ver Privacidad y PII.
"send_meta_conversions devuelve insufficient_scope"
Esta herramienta requiere scope mcp:write en el token, write-back del workspace habilitado y rol de administrador del workspace. Verifica las tres condiciones.