Todos los errores tienen el mismo formato: {"error": {"type", "message", …}}. Busca el type que recibiste para ver qué pasó y qué hacer. La consola de estas páginas también te lo explica al momento.
| HTTP | Tipo | Qué pasó | Qué hacer |
|---|---|---|---|
| 401 | unauthorized | La llave falta, no existe o fue revocada. | Conecta una llave activa. Las emite tu administrador. |
| 403 | forbidden | La llave es de solo lectura o tu IP no está autorizada. | Pide a tu administrador una llave con permiso de escritura o que autorice tu IP. |
| 403 | access_disabled | El acceso de tu cuenta está suspendido. | Contacta al administrador. |
| 403 | real_mode_not_allowed | Tu cuenta solo está autorizada para el modo simulado. | Pide a tu administrador que autorice la cuenta para operar con la DIAN. |
| 404 | not_found | El recurso no existe o es de otra empresa. | Revisa el id o el CUFE. Cada cuenta solo ve sus propios documentos. |
| 400 | idempotency_key_required | Falta la cabecera Idempotency-Key. | Envía un valor único por documento, por ejemplo el número de tu pedido. |
| 409 | idempotency_conflict | Usaste la misma Idempotency-Key con otro cuerpo. | Usa una llave nueva para cada documento nuevo. |
| 409 | idempotency_in_progress | La primera petición con esa llave sigue en curso. | Espera y consulta GET /documentos antes de reintentar. |
| 422 | validation_error | Algún dato no es válido. | En error.fields está cada campo con su problema. |
| 422 | dian_rejected | La DIAN rechazó el documento. | Lee las reglas en error.dian_errors, corrige y reenvía con POST /documentos/{id}/reintentar: el número se conserva. |
| 422 | configuration_incomplete | Falta configuración para operar contra la DIAN. | Completa lo que indica faltantes, en el panel o con la ruta «Pasar a producción». |
| 422 | numbering_missing | No hay una numeración vigente para ese documento. | Registra tu resolución de numeración con POST /numeracion. |
| 422 | certificate_invalid | No se pudo abrir el certificado. | Revisa la contraseña y que sea un archivo .p12 o .pfx con clave privada. |
| 422 | dian_error | La DIAN respondió con un error a la consulta. | Revisa el SoftwareID y el NIT. |
| 409 | not_in_production | La cuenta está en habilitación: solo se envía el set de pruebas. | Aprueba el set y activa producción, o vuelve al modo simulado. |
| 409 | habilitation_required | Aún no se puede activar producción. | Sal del modo simulado y aprueba el set de facturación ante la DIAN. |
| 409 | already_in_production | Una cuenta en producción no vuelve al modo simulado. | Pide a tu administrador otra cuenta para tus pruebas. |
| 402 | documents_exhausted | Se agotaron los documentos que te asignó tu administrador. | Pídele más y reintenta con la misma Idempotency-Key. Solo aplica a documentos reales: el modo simulado no consume. |
| 409 | range_exhausted | Se agotó la numeración. | Registra una nueva resolución. |
| 409 | invalid_state | El documento no admite esa acción en su estado actual. | Consulta su estado con GET /documentos/{id}. |
| 409 | mode_mismatch | El documento se creó en otro modo. | Un documento simulado no se puede transmitir de verdad, ni al revés. |
| 409 | simulated | El modo simulado no envía correos a terceros. | La entrega funciona cuando operas contra la DIAN. |
| 409 | not_simulated | Esa acción solo existe en modo simulado. | Vuelve al modo simulado si aún no estás en producción. |
| 409 | test_set_not_running | No hay un set de pruebas en curso que detener. | Consulta su estado con GET /habilitacion. |
| 409 | test_set_not_paused | No hay un set pausado que reanudar. | Envía el set completo sin "reanudar". |
| 409 | range_in_use | La numeración ya tiene documentos emitidos y no se puede eliminar. | Ajusta su rango o vigencia, o registra una nueva. |
| 409 | test_set_running | El set de pruebas ya se está enviando. | Espera a que termine y consulta GET /habilitacion. |
| 429 | rate_limited | Superaste las 120 peticiones por minuto. | Espera lo que indica la cabecera Retry-After. |
| 503 | dian_unavailable | La DIAN no respondió a una consulta. | Reintenta más tarde. Los documentos emitidos no usan este error: quedan pendientes y responden 202. |
| 503 | pdf_unavailable | No se pudo generar el PDF en este momento. | Reintenta. El documento no se ve afectado. |
| 500 | internal_error | Tuvimos un problema de nuestro lado. | Reintenta con la misma Idempotency-Key: no se duplica. |