Códigos de Error
Referencia completa de errores HTTP de la API y códigos de error de la DIAN, con soluciones claras.
Errores HTTP
La API retorna códigos HTTP estándar. Todos los errores incluyen un body JSON con code, message y details.
| Código | Nombre | Descripción | Solución |
|---|---|---|---|
400 | Bad Request | Solicitud malformada o parámetros inválidos | Revisa el body y los parámetros requeridos |
401 | Unauthorized | API key faltante o inválida | Incluye un header Authorization válido |
403 | Forbidden | Sin permisos para este recurso | Verifica que tienes acceso al recurso y ambiente |
404 | Not Found | Recurso no encontrado | Verifica el ID y la ruta del endpoint |
422 | Unprocessable Entity | Datos válidos pero no procesables | Revisa reglas de negocio (cert vencido, NIT inválido) |
429 | Too Many Requests | Rate limit excedido | Espera y reintenta con exponential backoff |
500 | Internal Server Error | Error interno de MercaloAPI | Reintenta. Si persiste, contacta soporte |
502 | Bad Gateway | Error comunicación con DIAN | Reintenta en 1 min. DIAN puede estar en mantenimiento |
503 | Service Unavailable | Servicio en mantenimiento | Revisa status.mercaloapi.com para información |
Errores DIAN
Cuando la DIAN rechaza un documento, el campo dianErrors en la respuesta contiene los códigos específicos. Aquí los más comunes:
| Código DIAN | Significado | Solución |
|---|---|---|
FAD06 | NIT del adquiriente inválido | Verificar dígito de verificación del NIT |
FAD07 | Tipo de documento no válido | Usar tipos válidos: CC, CE, NIT, TI, PP |
FAD08 | Razón social no coincide | El nombre debe coincidir con el RUT del NIT |
FAJ21 | Fecha de emisión fuera de rango | La factura debe emitirse dentro de las 24h |
FAJ24 | Valor total no coincide | Verificar cálculos de subtotal + IVA = total |
FAD10 | Certificado digital vencido | Renovar el certificado .p12 con la CA |
FAB01 | Prefijo de resolución agotado | Solicitar nueva resolución de numeración |
FAB02 | Número de factura duplicado | Verificar consecutivo de numeración |
FAK10 | XML mal formado | MercaloAPI maneja esto, contacta soporte |
FAK40 | Firma digital inválida | Verificar que el .p12 esté correctamente cargado |
💡 Tip: MercaloAPI traduce automáticamente todos los errores DIAN al español y te da sugerencias de corrección en la respuesta de la API. Los documentos rechazados no cuentan contra tu cuota mensual.