Errores

Los errores de AdapterDian siguen RFC 7807 con un código estable y un correlation_id. Qué significa cada código y cuáles reintentar.

Todo error es application/problem+json (RFC 7807) con los mismos campos:

Respuesta de error

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 es estable: decide con él, no con title ni detail, que son texto para personas.
errors trae pares { field, message } cuando la petición no pasó la validación.
correlation_id también llega en la cabecera X-Correlation-Id. Puedes enviar tu propio X-Correlation-Id para seguir una petición entre tus sistemas.

Guarda el correlation_id

Inclúyelo cuando escribas a soporte: convierte «falló una factura» en una búsqueda.

Códigos

Estado	`code`	Qué hacer
401	`UNAUTHORIZED`, `API_KEY_EXPIRED`	Revisa o rota la llave. Ver Autenticación.
403	`FORBIDDEN`	A la llave le falta el permiso.
404	`DOCUMENT_NOT_FOUND`	El id no existe para tu tenant.
409	`IDEMPOTENCY_CONFLICT`	La `Idempotency-Key` ya se usó con otro cuerpo. Ver Idempotencia.
409	`INVALID_STATE_TRANSITION`	La operación no se permite en el estado actual del documento.
422	`VALIDATION_FAILED`	La petición no cumple el contrato; mira `errors`.
422	`INVARIANT_VIOLATED`	El documento incumple una regla de emisión.
422	`CATALOG_CODE_UNKNOWN`	Un código de catálogo DIAN no existe.
422	`ROUNDING_OUT_OF_RANGE`	El ajuste de redondeo excede el máximo permitido.
422	`TOTALS_MISMATCH`	Los totales no coinciden con los que calculó el proveedor.
422	`PROVIDER_VALIDATION_FAILED`	El proveedor rechazó el documento.
422	`PROVIDER_REJECTED_BY_TAX_AUTHORITY`	La DIAN no validó el documento.
429	`PROVIDER_RATE_LIMITED`	Reintenta después de la cabecera `Retry-After`.
501	`NOT_IMPLEMENTED`	La operación todavía no existe. No reintentes.
502	`PROVIDER_AUTH_FAILED`	Reintenta más tarde.
503	`PROVIDER_UNAVAILABLE`	Reintenta más tarde.
504	`PROVIDER_TIMEOUT`	Reintenta más tarde.
500	`INTERNAL`	Escribe a soporte con el `correlation_id`.

Qué reintentar

Solo PROVIDER_RATE_LIMITED, PROVIDER_UNAVAILABLE, PROVIDER_TIMEOUT y PROVIDER_AUTH_FAILED son transitorios. Reintentar un error de validación no lo convierte en aceptación. Cuando reintentes un POST que emite, usa la misma Idempotency-Key.