Errores de la API

Formato application/problem+json (RFC 9457) · versión 2026-10-21

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.

{
  "type": "https://trevol.si/api/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_…"
}

Código	HTTP	Cuándo	¿Reintentar?
`authentication_required`	401	Falta Authorization: Bearer con la llave.	No (corrige primero)
`invalid_api_key`	401	La llave no existe, fue revocada o no es de la API (debe empezar por tvl_test_ o tvl_live_).	No (corrige primero)
`permission_denied`	403	La llave es de solo lectura, o la petición viene de una IP que la llave no permite.	No (corrige primero)
`not_found`	404	La ruta no existe, o el documento no es de la empresa y el ambiente de la llave.	No (corrige primero)
`method_not_allowed`	405	La ruta existe pero no con ese método (la cabecera Allow dice cuáles).	No (corrige primero)
`unsupported_version`	400	Trevol-Version trae una versión que no existe.	No (corrige primero)
`invalid_json`	400	El cuerpo no es JSON o no es un objeto.	No (corrige primero)
`invalid_request`	400	El pedido no es válido (por ejemplo, una Idempotency-Key con caracteres no permitidos).	No (corrige primero)
`idempotency_key_required`	400	Crear o corregir un documento sin Idempotency-Key.	No (corrige primero)
`idempotency_key_reused`	422	La misma Idempotency-Key con otro cuerpo u otra operación. Usa una clave nueva por pedido.	No (corrige primero)
`request_in_progress`	409	Otra petición está enviando ese documento ahora. Consulta su estado en unos segundos.	Sí
`validation_error`	422	Los datos no son válidos. errors[] trae cada campo con su puntero (RFC 6901). No se gastó ningún número.	No (corrige primero)
`external_id_in_use`	409	Ya hay un documento con ese external_id en la empresa y el ambiente; existing_id dice cuál.	No (corrige primero)
`invalid_state`	409	El documento no está en un estado que lo permita (por ejemplo, corregir uno ya validado: para eso es la nota).	No (corrige primero)
`dian_rejected`	422	La DIAN rechazó el documento. document trae el documento con dian.rules traducidas; se corrige con PUT y el mismo número.	No (corrige primero)
`company_not_enabled`	422	La empresa no ha terminado la habilitación ante la DIAN.	No (corrige primero)
`numbering_unavailable`	422	No hay numeración disponible: sin resolución activa, agotada o vencida, o ContaPyme lleva la numeración de producción.	No (corrige primero)
`certificate_problem`	422	El certificado de la empresa falta o no sirve para firmar.	No (corrige primero)
`file_unavailable`	409	El documento todavía no tiene archivos (no está validado), o no se pudieron preparar ahora (503, reintentable).	No (corrige primero)
`insufficient_balance`	402	Producción sin saldo. El documento queda pending con su número y se envía al reintentar con saldo.	No (corrige primero)
`rate_limited`	429	Pasaste un límite de la llave. Retry-After dice cuántos segundos esperar.	Sí
`dian_unavailable`	503	La DIAN no contestó. Reintenta con la misma Idempotency-Key: sigue con el mismo documento.	Sí
`internal_error`	500	Error de Trevol. Escríbenos con el request_id.	Sí

Reglas de la DIAN

Cuando la DIAN valida o rechaza, document.dian.rules trae cada regla con su code (por ejemplo FAK24), severity (rejection o notification), el message literal de la DIAN y, además, area, explanation, fix y, cuando aplica, field. El área se deduce del grupo del XML de la regla (Anexo técnico 1.9):

area	Dónde se corrige
`customer`	Los datos del cliente (customer).
`items`	Una línea (items): unidad, impuestos, código…
`payment`	El pago (payment).
`totals / trevol`	Algo que calcula o arma Trevol (totales, CUFE, firma): escríbenos con el request_id.
`issuer`	Los datos de la empresa que emite (RUT, certificado): se corrigen en la app, no en el pedido.
`numbering`	La resolución de numeración: en la app, consulta otra vez las resoluciones de la DIAN.
`invoice / concept`	En una nota: la factura que corrige o el concepto de corrección.
`document`	Otro punto del documento: lee el mensaje literal de la DIAN.

Una notificación no impide la validación. Un rechazo no bloquea nada más: el documento queda rejected con su número, y se corrige con PUT.