Errores

Cada error trae código de máquina, mensaje humano y doc_url. La tabla completa.

La forma de todo error

{
  "error": {
    "code": "monthly_limit_exceeded",
    "message": "El cupo del mes se agotó: llevabas $1.000.000 y renueva el 1 de octubre.",
    "doc_url": "https://docs.tikin.is/conceptos/errores#monthly_limit_exceeded",
    "details": { "used": "100000000", "limit": "100000000", "resets_at": "2026-10-01T00:00:00Z" }
  }
}

code es para tu código: estable, en inglés, se puede hacer switch sobre él.
message es para un humano: dice qué pasó con números, no "invalid request".
details trae los datos de la regla cuando aplica (cuánto llevabas, cuándo renueva).
doc_url apunta al ancla de ese código en esta página (/conceptos/errores#<code>) — el link del error resuelve de verdad.

Toda respuesta del API — éxito o error — trae el header Tikin-Request-Id: el id único de ese request. Guárdalo en tus logs junto a cada llamada, y cítalo al escribir a soporte: con él encontramos tu request en segundos, sin arqueología. Un reporte sin request id es una búsqueda; con él, es un lookup.

La tabla

HTTP	Significa	Qué haces
`400`	La forma del pedido es inválida — falta un campo, decimales de más, origen==destino	Arregla el request; reintentar igual dará igual
`401`	Token ausente, inválido o revocado	Revisa la credencial (`tk_live_…`)
`403`	`authority_insufficient` — el rol del miembro en ESA cuenta no puede hacer esto	No es el token: es el permiso dentro de la cuenta
`404`	El recurso no existe o no es de tu tenant — misma respuesta a propósito	No se filtra ni la existencia de lo ajeno
`409`	La misma `Idempotency-Key` con otro cuerpo, o una transición ilegal (disparar un lote que no está `ready`)	Es un bug de tu lado: no reintentes, investiga
`422`	La regla de negocio dijo no — el `code` dice cuál	Lee el código (tabla abajo); reintentar sin cambiar la realidad dará lo mismo
`503`	No se pudo saber — el libro no contestó	Reintenta con la misma llave; jamás te inventamos un éxito ni un cero

Los códigos del `422`

`code`	La regla
`insufficient_funds`	No alcanza — contra el disponible, no el total (lo retenido no se gasta)
`capability_cannot_send`	La cuenta no declaró verificación: recibe, pero no saca
`below_minimum`	Bajo el mínimo por operación
`above_per_operation_limit`	Sobre el tope por operación
`monthly_limit_exceeded`	El cupo del mes se agotó — `details` dice cuánto llevaba y cuándo renueva

El catálogo, código por código

Cada code tiene su ancla aquí — es a donde apunta el doc_url del error.

`missing_field`

400 — falta un campo obligatorio en el cuerpo; details.field dice cuál.

`invalid_field`

400 — un campo tiene forma inválida (decimales en un monto, alias mal formado); details ⇒ {field, reason}.

`missing_query`

400 — al lookup le falta el criterio: exactamente UNO de alias o phone; los dos, o ninguno, cae aquí.

`missing_idempotency_key`

400 — el endpoint mueve dinero y el header Idempotency-Key no vino. No es opcional: genera un UUID y guárdalo ANTES de mandar.

`idempotency_key_reused`

409 — la misma llave con OTRO cuerpo (bytes de archivos incluidos). Eso no es un reintento, es un bug tuyo: investiga antes de tocar nada.

`invalid_state`

409 — la transición no es legal desde el estado actual (disparar un lote que no está ready, cancelar un payout in_progress); details ⇒ {current, allowed[]}.

`unauthorized`

401 — token ausente, inválido o revocado. Revisa la credencial tk_live_….

`insufficient_scope`

401 — el token es válido pero no tiene el scope que este endpoint exige (lookup, transfers, payouts…). Pide un token con el scope justo.

`authority_insufficient`

403 — el rol del miembro en ESA cuenta no puede hacer esto. No es el token: es el permiso dentro de la cuenta.

`not_found`

404 — el recurso no existe o no es de tu tenant: misma respuesta a propósito, no se filtra ni la existencia de lo ajeno.

`alias_taken`

422 — ese alias ya es de otra cuenta en tu tenant. El alias es único dentro del tenant.

`alias_reserved`

422 — el alias está en la lista reservada de la plataforma (marcas, términos protegidos). Elige otro.

`alias_in_quarantine`

422 — el alias fue liberado hace menos de 90 días y está en cuarentena para que nadie herede pagos ajenos. Espera o elige otro.

`insufficient_funds`

422 — no alcanza, contra el disponible (lo retenido no se gasta); details ⇒ {available, requested}.

`capability_cannot_send`

422 — la cuenta no declaró verificación: recibe, pero no saca. Declara el KYC con PUT /v1/accounts/{account_id}/verification.

`below_minimum`

422 — el monto está bajo el mínimo por operación; details trae el mínimo.

`above_per_operation_limit`

422 — el monto supera el tope por operación; details trae el tope.

`monthly_limit_exceeded`

422 — el cupo del mes se agotó; details ⇒ {used, limit, resets_at}.

`rate_limited`

429 — demasiado rápido. Respeta Retry-After (segundos) y reintenta con backoff + jitter.

`ledger_unavailable`

503 — el libro no contestó: no se supo. Reintenta con la misma Idempotency-Key; jamás te inventamos un éxito ni un cero.

La regla de oro

4xx = el problema es del pedido (arréglalo). 503 = el problema fue nuestro o del camino (reintenta con la misma llave). Nunca trates un 422 como transitorio: la regla va a decir que no otra vez.