Códigos de Error

Código HTTP	Type	Mensaje	Descripción
400	Bad Request	Datos inválidos	El body de la petición tiene campos faltantes o con formato incorrecto
401	Unauthorized	API Key requerida	No se proporcionó el header X-Api-Key
401	Unauthorized	API Key inválida	La API Key no existe, fue revocada o está inactiva
403	Forbidden	Cupo agotado	Se alcanzó el límite de documentos de la suscripción
404	Not Found	Recurso no encontrado	El documento, cliente o empresa solicitado no existe
409	Conflict	Referencia duplicada	Ya existe un documento con la misma referencia_externa para esta empresa
429	Too Many Requests	Rate limit excedido	Se superó el número máximo de peticiones por minuto
500	Internal Server Error	Error interno	Error inesperado del servidor

Códigos de Error Específicos (DIAN)

Código Interno	HTTP	Descripción
VALIDATION_ERROR	400	Datos proporcionados no son válidos (campos faltantes, formato incorrecto).
DIAN_VALIDATION_FAILED	502	La DIAN rechazó el documento. El campo details.dian_errors contiene la lista de errores específicos.
DIAN_TRANSMISSION_ERROR	502	No fue posible conectar con la DIAN. Retryable = true.
DIAN_TIMEOUT	502	La DIAN no respondió en 30 segundos. Retryable = true.
DIAN_SIGNATURE_ERROR	502	La firma digital fue rechazada por la DIAN.
CERT_NOT_FOUND	400	El archivo del certificado digital .p12 no fue encontrado en el servidor.
CERT_EXPIRED	400	El certificado digital ha vencido. Renuévelo con su autoridad certificadora.
CERT_INVALID_PASSWORD	400	La contraseña del certificado digital es incorrecta.
QUOTA_EXCEEDED	403	Se alcanzó el límite de documentos de la suscripción. Actualice su plan.
DUPLICATE_RECORD	409	Ya existe un documento con la misma referencia_externa o valor único.
CONFLICT	409	Operación en conflicto (duplicado concurrente o idempotencia de payload).
DB_CONNECTION_TIMEOUT	503	No se pudo conectar con la base de datos. Retryable = true.

Formato de Respuesta de Error

JSON

{
  "success": false,
  "error": {
    "code": "DIAN_VALIDATION_FAILED",
    "message": "La DIAN rechazó el documento por errores de validación.",
    "details": {
      "dian_errors": ["Regla FAJ42: NIT del emisor no coincide"],
      "document_id": 7,
      "suggestion": "Verifique que el NIT de la empresa coincida con el configurado en la DIAN."
    },
    "retryable": false
  }
}

Siempre verifica el campo 'success' antes de procesar la respuesta

Los errores 5xx son temporales. Implementa un retry con backoff exponencial

Los errores 4xx indican problemas con la petición. Verifica los datos enviados

Rate Limiting

Cada API Key tiene un límite de peticiones configurado (por defecto: 100 req/min).

Headers

HTTP

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1714000000

Header	Descripción
X-RateLimit-Limit	Número máximo de peticiones por ventana
X-RateLimit-Remaining	Peticiones restantes en la ventana actual
X-RateLimit-Reset	Timestamp UNIX cuando se resetea la ventana

Best Practices

Implementa un sistema de colas para envíos masivos
Usa caching para evitar consultas repetitivas
Contacta soporte si necesitas un límite mayor