Documentación · Errores · API v1 · versión 2026-10-22
Errores
Catálogo de errores de la API de Trevol: códigos estables, estado HTTP, cuándo pasan y si se reintentan. Formato application/problem+json (RFC 9457).
Cada error trae un code estable (programa contra él, no contra el texto), el estado HTTP, un detail en español, retryable y el request_id de la petición. El type apunta a esta página, con un ancla por código: https://platform.trevol.si/docs/errores#validation_error.
Cuando la DIAN rechaza un documento, document.dian.rules trae cada regla con su explicación y cómo corregirla: Reglas de la DIAN. Qué se reintenta y cómo: Reintentos.
Autenticación y permisos
authentication_required
Falta la llave de la API · HTTP 401 · No se reintenta: corrige primero
Falta
Authorization: Bearercon la llave.invalid_api_key
La llave de la API no es válida · HTTP 401 · No se reintenta: corrige primero
La llave no existe, fue revocada o no es de la API (debe empezar por
tvl_test_otvl_live_).permission_denied
Sin permiso para esto · HTTP 403 · No se reintenta: corrige primero
La llave es de solo lectura, o la petición viene de una IP que la llave no permite.
El pedido
not_found
No existe · HTTP 404 · No se reintenta: corrige primero
La ruta no existe, o el documento no es de la empresa y el ambiente de la llave.
method_not_allowed
Método no permitido · HTTP 405 · No se reintenta: corrige primero
La ruta existe pero no con ese método (la cabecera
Allowdice cuáles).unsupported_version
Versión de la API desconocida · HTTP 400 · No se reintenta: corrige primero
Trevol-Versiontrae una versión que no existe.invalid_json
El cuerpo no es JSON válido · HTTP 400 · No se reintenta: corrige primero
El cuerpo no es JSON o no es un objeto.
invalid_request
El pedido no es válido · HTTP 400 · No se reintenta: corrige primero
El pedido no es válido (por ejemplo, una
Idempotency-Keycon caracteres no permitidos).validation_error
Los datos no son válidos · HTTP 422 · No se reintenta: corrige primero
Los datos no son válidos.
errors[]trae cada campo con su puntero (RFC 6901). No se gastó ningún número.
Idempotencia y duplicados
idempotency_key_required
Falta Idempotency-Key · HTTP 400 · No se reintenta: corrige primero
Crear o corregir un documento sin
Idempotency-Key.idempotency_key_reused
Esa Idempotency-Key ya se usó con otro pedido · HTTP 422 · No se reintenta: corrige primero
La misma
Idempotency-Keycon otro cuerpo u otra operación. Usa una clave nueva por pedido.request_in_progress
Ese pedido todavía se está procesando · HTTP 409 · Se puede reintentar
Otra petición está enviando ese documento ahora. Consulta su estado en unos segundos.
external_id_in_use
Ese external_id ya existe · HTTP 409 · No se reintenta: corrige primero
Ya hay un documento con ese
external_iden la empresa y el ambiente;existing_iddice cuál (con el prefijo de su recurso). Elexternal_ides único entre facturas, notas, documentos soporte y equivalentes (y sus notas); aparte, entre nóminas y sus ajustes; y aparte, entre eventos RADIAN.duplicate_document
Ya existe un documento igual · HTTP 409 · No se reintenta: corrige primero
Ya hay un documento vivo igual: una nómina (102) del mismo trabajador y mes en producción, o un evento RADIAN del mismo código sobre la misma factura.
existing_iddice cuál (pr_…,rev_…). Para reintentar un evento:POST /v1/radian_events/{id}/send; para cambiar una nómina: una nota de ajuste.
Documentos y la DIAN
invalid_state
El documento no está en un estado que lo permita · HTTP 409 · No se reintenta: corrige primero
El documento no está en un estado que lo permita (por ejemplo, corregir uno ya validado: para eso es la nota; un
PUTsobre un documento que Trevol o la DIAN están verificando —también el set de pruebas de la nómina y del documento equivalente—: espera el resultado; o reenviar un evento RADIAN rechazado: un rechazo es final).previous_event_pending
Falta el evento anterior en la DIAN · HTTP 409 · Se puede reintentar
Solo en la versión 2026-10-21: el evento (031, 032, 033) necesita que la DIAN muestre el anterior (
previous) y todavía no aparece. No se envió nada; el evento queda en error con su número (viene endocument): reintenta conPOST /v1/radian_events/{id}/send. En 2026-10-22 es un 202processingy Trevol lo manda cuando aparezca.tacit_acceptance_not_due
La aceptación tácita todavía no procede · HTTP 422 · No se reintenta: corrige primero
La aceptación tácita (034) todavía no procede.
available_fromdice desde cuándo (3 días hábiles después del recibo del bien) yruleslas reglas LGC que lo impiden (las locales llevanlocal: true). El evento queda en error con su número: reintenta conPOST …/sendcuando proceda.GET /v1/invoices/{id}/tacit_acceptance(o, por CUFE,GET /v1/radian_events/tacit_acceptance?cufe=…) lo dice antes.dian_rejected
La DIAN rechazó el documento · HTTP 422 · No se reintenta: corrige primero
La DIAN rechazó el documento.
documenttrae el documento condian.rulestraducidas (ver las reglas de la DIAN); se corrige conPUTy el mismo número.file_unavailable
El archivo no está disponible · HTTP 409 · No se reintenta: corrige primero
El documento todavía no tiene archivos (no está validado), o no se pudieron preparar ahora (503, reintentable).
dian_unavailable
La DIAN no respondió · HTTP 503 · Se puede reintentar
Solo en la versión 2026-10-21: la DIAN no contestó. El documento queda en error y Trevol lo verifica en segundo plano (solo consulta; no reenvía). Reintenta con la misma
Idempotency-Key: sigue con el mismo documento. En 2026-10-22 la respuesta es un 202processing.
Empresa y numeración
company_not_enabled
La empresa no está habilitada para facturar · HTTP 422 · No se reintenta: corrige primero
La empresa no ha terminado la habilitación ante la DIAN, o le falta algo para esa familia de documentos.
reasondice qué:missing_software(el software del modo),missing_pin,payroll_not_enabled(la nómina no está habilitada ni en pruebas) omissing_legal_representative(eventos 030 y 032). Se revisa antes de numerar.numbering_unavailable
La numeración no está disponible · HTTP 422 · No se reintenta: corrige primero
No hay numeración disponible: sin resolución activa (o sin rango de documento soporte o POS), agotada o vencida, o ContaPyme lleva la numeración de producción.
reason:no_resolution,resolution_exhausted,resolution_expired,resolution_not_yet_valid,prefix_in_useomissing_technical_key(POS).certificate_problem
Hay un problema con el certificado de la empresa · HTTP 422 · No se reintenta: corrige primero
El certificado de la empresa falta o no sirve para firmar.
Saldo y recargas
insufficient_balance
No hay saldo · HTTP 402 · No se reintenta: corrige primero
Producción sin saldo. El documento queda
pendingcon su número y se envía al reintentar con saldo.top_up_below_minimum
La recarga es menor que la mínima · HTTP 422 · No se reintenta: corrige primero
Preparar una recarga (
POST /v1/balance/top_ups) por menos de la recarga mínima ($ 5.000).minimum_copdice cuánto es.top_up_above_maximum
La recarga es mayor que la máxima · HTTP 422 · No se reintenta: corrige primero
Preparar una recarga (
POST /v1/balance/top_ups) por más de la recarga máxima.maximum_copdice cuánto es.top_ups_unavailable
Las recargas no están disponibles · HTTP 503 · Se puede reintentar
Las recargas no están disponibles en este momento.
Retry-Afterdice cuándo volver a intentar.
Límites y disponibilidad
webhook_limit_reached
Ya hay el máximo de endpoints de webhooks · HTTP 409 · No se reintenta: corrige primero
Ya hay 5 webhooks en la empresa y el ambiente. Borra uno para crear otro.
rate_limited
Demasiadas peticiones · HTTP 429 · Se puede reintentar
Pasaste un límite de la llave.
Retry-Afterdice cuántos segundos esperar.internal_error
Error interno de Trevol · HTTP 500 · Se puede reintentar
Error de Trevol. Escríbenos con el
request_id.
{
"type": "https://platform.trevol.si/docs/errores#validation_error",
"title": "Los datos no son válidos",
"status": 422,
"code": "validation_error",
"detail": "La tarifa de IVA debe ser una de la tabla 13.3.11: 0.00, 5.00, 16.00, 19.00.",
"errors": [
{ "field": "items[0].taxes[0].rate", "pointer": "/items/0/taxes/0/rate", "message": "…" }
],
"retryable": false,
"request_id": "req_…"
}