Referencia

Errores y estados

Todos los errores tienen la misma forma. Aquí ves qué significa cada código, qué hacer y en qué estado puede quedar un documento.

Forma del error#

json

{ "error": { "code": "quota_exceeded", "message": "Tu empresa ya usó los 450 documentos…" }, "request_id": "…" }

error.code: código estable, para tu lógica.
error.message: texto para mostrar o registrar.
error.details: lista de detalles, por ejemplo qué campo está mal.
request_id: guárdalo en tus registros. Le sirve a soporte para encontrar el caso.

Código	Estado	Qué hacer
`dian_error`	422	El documento quedó registrado y la DIAN lo rechazó o no respondió. No lo emitas otra vez: consulta `GET /facturas/{id}`. Si `reintento_programado` tiene fecha, Conta360 lo reenvía solo
`quota_exceeded`	409	Se agotó el cupo de documentos del mes. La empresa debe comprar adicionales o cambiar de plan. Avisa en pantalla al cajero
`conflict`	409	Usaste la misma `Idempotency-Key` con otro contenido
`invalid_token`	401	Token vencido o integración revocada: pide un token nuevo; si vuelve a fallar, habla con el administrador
`insufficient_scope`	403	Falta un alcance. El encabezado `X-Required-Scope` dice cuál: pídeselo al administrador
`rate_limited`	429	Pasaste el límite por minuto. Espera lo que diga `Retry-After`
`invalid_request`	400	Revisa `details`: dice qué campo está mal

openapi.yaml también define invalid_client, forbidden, not_found, unprocessable y server_error.

Encabezado	Cuándo llega
`X-Required-Scope`	Con `403 insufficient_scope`: el alcance que falta
`Retry-After`	Con `429 rate_limited`: cuánto esperar antes de reintentar
`Idempotent-Replay`	`true` cuando la respuesta es la repetición de un envío anterior con la misma `Idempotency-Key`

El campo estado de un documento puede ser:

`estado`	Qué significa
`draft`	Borrador: guardado en Conta360 sin enviarlo a la DIAN
`pending`	Enviando a la DIAN
`validated`	Validado por la DIAN
`issued`	Por definir
`rejected`	Por definir
`error`	Por definir
`deleted`	Eliminado