Errores
Todo error tiene la misma forma:
{ "error": { "code": "dte_invalido", "message": "…", "details": {} } }Decida siempre por code, nunca por el texto de message. Los códigos son contrato público y no
cambian de nombre.
Códigos
Sección titulada «Códigos»| HTTP | code |
Qué pasó | Qué hacer |
|---|---|---|---|
| 400 | datos_invalidos |
Cuerpo o parámetros inválidos; details = [{ ruta, mensaje }] |
Corrija cada ruta y repita. |
| 400 | dte_invalido |
El DTE no cumple el esquema del MH; details.problemas = [{ ruta, mensaje, regla }]. No se emitió nada |
Corrija y vuelva a validar. |
| 401 | no_autenticado |
Falta sesión, o la clave es inválida, fue revocada o expiró | Revise la clave o cree otra. |
| 403 | sin_permiso |
Falta el permiso details.permiso |
Use una clave con ese permiso. |
| 403 | origen_no_permitido |
Petición con cookie desde otro origen | Use el panel o una clave de API. |
| 404 | no_encontrado |
El recurso no existe en su organización | Revise el id o el código. |
| 409 | sin_organizacion, sin_organizacion_activa |
La sesión no tiene organización activa | Cree o active una organización. |
| 409 | emisor_no_configurado, credenciales_incompletas, sin_punto_venta |
Falta configuración | Complétela en el panel (Emisor). |
| 409 | nit_bloqueado |
El NIT del emisor no puede cambiarse después de emitir documentos | Cree otra organización para otro NIT. |
| 409 | estado_invalido |
El documento no está en un estado que permita la operación | Consulte el documento. |
| 409 | ambiente_distinto |
El documento o evento es de otro ambiente | Use la clave del ambiente correcto. |
| 409 | retorno_excedido |
El retorno supera lo que queda del documento | details.disponible dice cuánto queda. |
| 409 | retorno_vigente |
El documento tiene un retorno vigente | Invalide antes el retorno (details.codigoGeneracion). |
| 409 | idempotencia_distinta |
Esa Idempotency-Key ya se usó con otro cuerpo |
Otra clave para otro documento; el mismo cuerpo para el mismo. |
| 409 | idempotencia_en_curso |
El primer intento sigue en proceso | Espere y repita con la misma clave. |
| 409 | cliente_repetido, producto_repetido, codigo_repetido |
Ya existe un registro con ese documento o código | Actualice el existente. |
| 409 | sin_archivo |
El documento sigue pendiente y aún no tiene archivo | Consulte de nuevo en unos minutos. |
| 409 | simulador_inactivo |
Credenciales de prueba pedidas a un servidor sin simulador | Cargue credenciales reales del MH. |
| 422 | dte_rechazado |
El MH rechazó el documento; el número de control queda como rechazado | Muestre details.mh.observaciones, corrija y emita uno nuevo con otra Idempotency-Key. |
| 422 | invalidacion_rechazada |
El MH rechazó la invalidación (a menudo, fuera de plazo) | Revise details.mh y los plazos. |
| 422 | contingencia_rechazada |
El MH rechazó el evento de contingencia | Revise details.mh. |
| 422 | evento_rechazado |
El MH rechazó un retorno u operaciones especiales | Corrija y reenvíe con otra Idempotency-Key. |
| 429 | limite_excedido |
Demasiadas peticiones | Espere Retry-After segundos. |
| 500 | error_interno |
Error inesperado del servidor | Reintente; si persiste, repórtelo. |
| 502 | mh_credenciales_rechazadas |
El MH no aceptó la contraseña de API o el certificado | Revise Emisor → Credenciales del MH. |
| 502 | mh_no_disponible |
No se pudo hablar con el MH; no se consumió número de control | Reintente con la misma Idempotency-Key. |
| 502 | emision_fallida |
No se pudo firmar; el documento quedó rechazado sin transmitirse |
Revise el certificado y emita de nuevo. |
| 502 | emision_incierta |
No se pudo confirmar el resultado; el documento queda pendiente |
No emita otro. Consulte details.codigoGeneracion; se concilia solo con el MH. |
En details.mh el MH informa { codigo, mensaje, observaciones[] }.