Saltar al contenido principal

Errores de la API

Cuando una llamada a la API de Clatri falla, la respuesta es application/problem+json (RFC 9457):

{
  "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​

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. No reintentes sin corregirlo.

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​

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​

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).

unauthorized​

Falta la cabecera Authorization, no tiene la forma Bearer <token> o el token no existe.

Qué hacer: revisa que envías Authorization: Bearer clt_mcp_… completo, sin espacios de más.

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​

El token caducó (duran 6 meses).

Qué hacer: crea uno nuevo y reemplázalo.

402 — Suscripción​

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).

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​

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​

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​

No existe una herramienta con ese nombre.

Qué hacer: revisa el nombre en GET /v1/tools.

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.

Qué hacer: haz esa acción desde la app o el chat de Clatri.

not_found​

La ruta no existe.

Qué hacer: revisa la URL. Las rutas válidas están en la guía.

405 — Método no permitido​

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​

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​

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​

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​

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​

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​

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​

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​

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.