AdapterDian by Piensa IT
On this page

Errors

AdapterDian errors follow RFC 7807 with a stable code and a correlation_id. What each code means and which ones to retry.

Every error is application/problem+json (RFC 7807) with the same fields:

Error response
HTTP/2 409
Content-Type: application/problem+json
X-Correlation-Id: 3e2f4360-fd4f-4db8-a3f0-f6d9361462af

{
  "type": "https://docs.piensa.it/errors/idempotency-conflict",
  "title": "La clave de idempotencia ya se uso con otro contenido",
  "status": 409,
  "code": "IDEMPOTENCY_CONFLICT",
  "detail": "…",
  "correlation_id": "3e2f4360-fd4f-4db8-a3f0-f6d9361462af"
}
  • code is stable: branch on it, not on title or detail, which are human-readable text in Spanish.
  • errors lists { field, message } pairs when the request failed validation.
  • correlation_id also comes in the X-Correlation-Id header. You can send your own X-Correlation-Id to follow a request across your systems.

Keep the correlation_id

Include it when you write to support: it turns “an invoice failed” into a lookup.

Codes

Status code What to do
401 UNAUTHORIZED, API_KEY_EXPIRED Check or rotate the key. See Authentication.
403 FORBIDDEN The key lacks the permission.
404 DOCUMENT_NOT_FOUND The id doesn’t exist for your tenant.
409 IDEMPOTENCY_CONFLICT The Idempotency-Key was already used with a different body. See Idempotency.
409 INVALID_STATE_TRANSITION The operation isn’t allowed in the document’s current status.
422 VALIDATION_FAILED The request doesn’t match the contract; see errors.
422 INVARIANT_VIOLATED The document breaks an issuing rule.
422 CATALOG_CODE_UNKNOWN A DIAN catalog code doesn’t exist.
422 ROUNDING_OUT_OF_RANGE The rounding adjustment exceeds the allowed maximum.
422 TOTALS_MISMATCH The totals don’t match what the provider calculated.
422 PROVIDER_VALIDATION_FAILED The provider rejected the document.
422 PROVIDER_REJECTED_BY_TAX_AUTHORITY The DIAN didn’t validate the document.
429 PROVIDER_RATE_LIMITED Retry after the Retry-After header.
501 NOT_IMPLEMENTED The operation doesn’t exist yet. Don’t retry.
502 PROVIDER_AUTH_FAILED Retry later.
503 PROVIDER_UNAVAILABLE Retry later.
504 PROVIDER_TIMEOUT Retry later.
500 INTERNAL Write to support with the correlation_id.

What to retry

Only PROVIDER_RATE_LIMITED, PROVIDER_UNAVAILABLE, PROVIDER_TIMEOUT and PROVIDER_AUTH_FAILED are transient. Retrying a validation error doesn’t turn it into an acceptance. When you retry an issuing POST, reuse the same Idempotency-Key.