Error Codes

HTTP Code	Type	Message	Description
400	Bad Request	Invalid Data	The request body has missing or incorrectly formatted fields
401	Unauthorized	API Key required	The X-Api-Key header was not provided
401	Unauthorized	Invalid API Key	The API Key does not exist, was revoked or is inactive
403	Forbidden	Quota exceeded	The subscription document limit was reached
404	Not Found	Resource not found	The requested document, customer or company does not exist
409	Conflict	Duplicate reference	A document with the same referencia_externa already exists for this company
429	Too Many Requests	Rate limit exceeded	The maximum number of requests per minute was exceeded
500	Internal Server Error	Internal error	Unexpected server error

Specific Error Codes (DIAN)

Internal Code	HTTP	Description
VALIDATION_ERROR	400	Provided data is invalid (missing fields, incorrect format).
DIAN_VALIDATION_FAILED	502	DIAN rejected the document. The details.dian_errors field contains the specific error list.
DIAN_TRANSMISSION_ERROR	502	Could not connect to DIAN. Retryable = true.
DIAN_TIMEOUT	502	DIAN did not respond within 30 seconds. Retryable = true.
DIAN_SIGNATURE_ERROR	502	The digital signature was rejected by DIAN.
CERT_NOT_FOUND	400	The .p12 digital certificate file was not found on the server.
CERT_EXPIRED	400	The digital certificate has expired. Renew it with your certificate authority.
CERT_INVALID_PASSWORD	400	The digital certificate password is incorrect.
QUOTA_EXCEEDED	403	Subscription document limit reached. Upgrade your plan.
DUPLICATE_RECORD	409	A document with the same referencia_externa or unique value already exists.
CONFLICT	409	Conflicting operation (concurrent duplicate or payload idempotency).
DB_CONNECTION_TIMEOUT	503	Could not connect to the database. Retryable = true.

Error Response Format

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
  }
}

Always verify the 'success' field before processing the response

5xx errors are temporary. Implement a retry with exponential backoff

4xx errors indicate problems with the request. Check the sent data

Rate Limiting

Each API Key has a configured request limit (default: 100 req/min).

Headers

HTTP

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

Header	Description
X-RateLimit-Limit	Maximum number of requests per window
X-RateLimit-Remaining	Remaining requests in current window
X-RateLimit-Reset	UNIX timestamp when the window resets

Best Practices

Implement a queue system for mass submissions
Use caching to avoid repetitive queries
Contact support if you need a higher limit