# Errores de la API URL: https://docs.clatri.com/api/errors/ > Los códigos de error de la API de Clatri: qué significa cada uno, su estado HTTP y qué hacer para resolverlo desde tu integración. Cuando una llamada a la [API de Clatri](https://docs.clatri.com/api/) falla, la respuesta es `application/problem+json` ([RFC 9457](https://www.rfc-editor.org/rfc/rfc9457)): ```json { "type": "https://docs.clatri.com/api/errors#tool_error", "title": "The tool could not complete the request", "status": 422, "detail": "Error: account not found.", "code": "tool_error", "request_id": "req_6c1d0e2a9b7f4e3c8a5d1f0b2e4c6a8d" } ``` - **`code`** es estable: úsalo en tu código para decidir qué hacer. Pueden aparecer códigos nuevos, pero los existentes no cambian dentro de `v1`. - **`type`** enlaza a la sección de esta página que explica ese código. - **`title`** y **`detail`** están en inglés y son para leer, no para comparar. - **`request_id`** identifica la llamada (también va en la cabecera `Clatri-Request-Id`). Inclúyelo si escribes a soporte. Los mensajes nunca incluyen tu token, trazas internas ni consultas a la base de datos. --- ## 400 — Petición inválida ### `validation_error` {#validation_error} La petición no es válida: el cuerpo no es un objeto JSON, falta o sobra un argumento, un valor tiene el tipo equivocado, `entity_id` no es un UUID o viene dentro del cuerpo, o un parámetro de la URL no es `true`/`false`. El `detail` dice qué campo falló. **Qué hacer:** compara el cuerpo con el `input_schema` de la herramienta en `GET /v1/tools` o en la [referencia](https://docs.clatri.com/api/reference/). No reintentes sin corregirlo. ### `idempotency_key_required` {#idempotency_key_required} La herramienta crea, edita o elimina datos y la petición no trae `Idempotency-Key`. **Qué hacer:** agrega la cabecera con un valor único por operación (por ejemplo, un UUID). Si la clave tiene caracteres no permitidos o más de 255, el error es `validation_error`. ### `dry_run_not_supported` {#dry_run_not_supported} Usaste `?dry_run=true` en una herramienta que no tiene vista previa. No se ejecutó nada. **Qué hacer:** quita `?dry_run=true`. Solo las herramientas con `supports_dry_run: true` en `GET /v1/tools` lo aceptan. ### `https_required` {#https_required} La petición llegó por HTTP sin cifrar. **Qué hacer:** usa `https://api.clatri.com/v1`. --- ## 401 — Autenticación Varios `401` seguidos pueden bloquear temporalmente el token o la IP (ver [`rate_limited`](#rate_limited)). ### `unauthorized` {#unauthorized} Falta la cabecera `Authorization`, no tiene la forma `Bearer ` o el token no existe. **Qué hacer:** revisa que envías `Authorization: Bearer clt_mcp_…` completo, sin espacios de más. ### `token_revoked` {#token_revoked} El token fue revocado. **Qué hacer:** crea uno nuevo en Ajustes → Conexiones → Agentes y APIs y reemplázalo en tu integración. ### `token_expired` {#token_expired} El token caducó (duran 6 meses). **Qué hacer:** crea uno nuevo y reemplázalo. --- ## 402 — Suscripción ### `subscription_inactive` {#subscription_inactive} La suscripción de Clatri del dueño del token no está activa. **Qué hacer:** renuévala. El mismo token vuelve a funcionar sin cambios. --- ## 403 — Permisos Varios `403` seguidos pueden bloquear temporalmente el token o la IP (ver [`rate_limited`](#rate_limited)). ### `scope_denied` {#scope_denied} El token no tiene el permiso que pide la herramienta (por ejemplo, quiere escribir y el token es de solo lectura). **Qué hacer:** edita los permisos del token en Ajustes → Conexiones → Agentes y APIs, o usa otro token. ### `domain_denied` {#domain_denied} La herramienta es de un área (Dinero, Salud, Administración, General) que el token no tiene. **Qué hacer:** agrega el área al token o usa otro token. ### `entity_denied` {#entity_denied} El token no puede usar la entidad de la ruta, o el cuerpo menciona un registro (una cuenta, una tarea…) que pertenece a otra entidad. **Qué hacer:** revisa el `entity_id` con `GET /v1/entities` y que los ids del cuerpo sean de esa misma entidad. Si necesitas otra entidad, agrégala al token. --- ## 404 — No encontrado ### `tool_not_found` {#tool_not_found} No existe una herramienta con ese nombre. **Qué hacer:** revisa el nombre en `GET /v1/tools`. ### `tool_not_available` {#tool_not_available} La herramienta existe pero no está disponible en la API (gestión de accesos, credenciales, consultas libres, programaciones…), o no está disponible para este tipo de token. Ver [qué herramientas no están disponibles](https://docs.clatri.com/api/#security). **Qué hacer:** haz esa acción desde la app o el chat de Clatri. ### `not_found` {#not_found} La ruta no existe. **Qué hacer:** revisa la URL. Las rutas válidas están en la [guía](https://docs.clatri.com/api/#how-it-works). --- ## 405 — Método no permitido ### `method_not_allowed` {#method_not_allowed} La ruta existe pero no con ese método (por ejemplo, `GET` a una herramienta). **Qué hacer:** las herramientas se llaman con `POST`; `/v1/me`, `/v1/entities` y `/v1/tools` con `GET`. --- ## 409 — Conflicto de idempotencia ### `idempotency_key_reused` {#idempotency_key_reused} Ya usaste esa `Idempotency-Key` con otra petición (otro cuerpo, otra herramienta, otra entidad u otros parámetros). No se ejecutó nada. **Qué hacer:** genera una clave nueva para cada operación distinta. Reutiliza una clave solo para reintentar exactamente la misma. ### `idempotency_in_progress` {#idempotency_in_progress} Una petición con esa misma clave todavía se está ejecutando. **Qué hacer:** espera los segundos que indica `Retry-After` y reintenta con la misma clave y el mismo cuerpo. Recibirás el resultado de la primera. --- ## 413 — Cuerpo demasiado grande ### `payload_too_large` {#payload_too_large} El cuerpo supera 256 KB. **Qué hacer:** divide la operación en varias llamadas. --- ## 422 — La herramienta no pudo completar la petición ### `tool_error` {#tool_error} La petición era válida y la herramienta se ejecutó, pero no pudo hacer lo que pediste: un registro que no existe, un saldo insuficiente, una fecha fuera de rango… El `detail` explica el motivo con el mensaje de la herramienta. **Qué hacer:** lee el `detail` y corrige los datos. Si usaste `Idempotency-Key`, este resultado queda guardado para esa clave: para un intento corregido, usa una clave nueva. --- ## 428 — Falta confirmación ### `confirmation_required` {#confirmation_required} La herramienta elimina o anula datos y la URL no trae `?confirm=true`. No se borró nada. **Qué hacer:** si de verdad quieres borrar, repite la llamada con `?confirm=true`. --- ## 429 — Demasiadas peticiones ### `rate_limited` {#rate_limited} Pasa en dos casos: - **Superaste un límite de tasa:** 120 lecturas o 30 escrituras por minuto por token, o 300 llamadas por minuto por entidad. - **Bloqueo temporal:** 20 respuestas `401` o `403` en 5 minutos, para el mismo token o la misma IP, bloquean durante 15 minutos. **Qué hacer:** espera los segundos de `Retry-After` antes de reintentar. Si es un bloqueo, corrige primero la causa de los `401`/`403`. --- ## 5xx — Error del servidor ### `internal_error` {#internal_error} Algo falló de nuestro lado. Si la llamada llevaba `Idempotency-Key`, la clave se libera. **Qué hacer:** reintenta más tarde con la misma clave. Si se repite, escríbenos con el `request_id`. ### `service_unavailable` {#service_unavailable} Un control de seguridad (límite de tasa, idempotencia, verificación de recursos) no se pudo completar en ese momento. Por seguridad, la llamada no se ejecuta. **Qué hacer:** reintenta en unos segundos, con la misma `Idempotency-Key` si la llevaba.