Errores

La forma

Todos los errores del API tienen la misma estructura, incluidos los de validación y los que no vienen de nuestro código:

{
  "status": 422,
  "code": "VALIDATION",
  "message": "texto legible en español",
  "errors": [
    { "rule": "FAJ43b", "field": "numbering_range_id", "message": "..." }
  ]
}

Campo	Descripción
status	El mismo código HTTP de la respuesta.
code	Identificador estable. Programa contra esto, no contra el texto.
message	Explicación en español, pensada para leerse. Puede cambiar.
errors	Detalle por campo. Vacío cuando no aplica.

Programa contra code

message está escrito para que un humano entienda qué pasó y puede mejorarse en cualquier momento. code es contrato.

Los códigos

Autenticación y permisos

code	HTTP	Qué pasó	Qué hacer
UNAUTHORIZED	401	Falta la cabecera, o el token es inválido o venció	Pide otro token
FORBIDDEN	403	La credencial es válida pero no abre esa puerta	Revisa qué credencial estás usando

Petición

code	HTTP	Qué pasó	Qué hacer
VALIDATION	400 / 422	Un campo falta, sobra o no cumple	Mira errors[]: dice el campo
BAD_REQUEST	400	La petición no encaja con el estado actual	Léelo: el mensaje dice qué falta
NOT_FOUND	404	No existe, o no es de tu emisor	Comprueba el id

Un campo de más también falla

El API rechaza cualquier propiedad que no esté en el contrato en vez de ignorarla. Mandar total, subtotal o iva en una factura devuelve 400 — los montos los calcula siempre el servidor.

Emisor mal configurado

code	HTTP	Qué pasó
CERT_MISSING	—	El emisor no tiene certificado digital cargado
CERT_EXPIRED	—	El certificado venció
CERT_NIT_MISMATCH	—	El certificado es de otro NIT
SOFTWARE_NOT_CONFIGURED	—	Falta registrar el software (id y PIN) ante la DIAN

Los cuatro se arreglan en la configuración del emisor, no en tu código.

Numeración

code	HTTP	Qué pasó	Qué hacer
RANGE_EXHAUSTED	422	Se acabó el rango autorizado	Pedirle otro a la DIAN
RANGE_EXPIRED	422	La resolución venció	Pedir una nueva

DIAN

code	HTTP	Qué pasó	Qué hacer
DIAN_VALIDATION	—	La DIAN rechazó el documento	Lee errors[]: son los suyos, literales
DIAN_UNAVAILABLE	—	La DIAN no respondió	Reintentar; el consecutivo no se pierde

Idempotencia

code	HTTP	Qué pasó
IDEMPOTENCY_CONFLICT	409	Ese reference_code ya existe para otro tipo de documento

Repetir un reference_code del mismo tipo no es un error: devuelve el documento que ya existe.

Plan

code	HTTP	Qué pasó
PLAN_REQUIRED	—	El emisor no tiene plan activo
PLAN_EXHAUSTED	—	Se agotó el cupo de documentos
PLAN_EXPIRED	—	El plan venció

Interno

code	HTTP	Qué pasó
INTERNAL	500	Algo se rompió de nuestro lado

{ "status": 500, "code": "INTERNAL", "message": "Error interno del servidor", "errors": [] }

Si se repite, escríbenos con el reference_code y la hora.

Límite de peticiones

300 por minuto y por IP. Al superarlo, 429.

Cómo tratarlos

Reintentables — la operación puede salir bien después: DIAN_UNAVAILABLE, INTERNAL, 429. Reintenta con espera creciente y el mismo reference_code: la idempotencia impide que se duplique.

No reintentables — hay que arreglar algo primero: VALIDATION, BAD_REQUEST, NOT_FOUND, FORBIDDEN, los cuatro de certificado y software, y los de plan. Reintentar sin cambiar nada da el mismo error.

Caso aparte: RANGE_EXHAUSTED y RANGE_EXPIRED no los arregla tu código ni el nuestro — hay que pedirle numeración a la DIAN. Vale la pena alertar antes de llegar al final del rango.