Manejo de Errores

Todas las responses de error de DVS comparten un envoltorio JSON común:

{
  "error_code": "071-403-document-type-not-allowed",
  "message": "Provider does not have access to the requested document_type/country/agreement combination",
  "additional_information": {
    "document_type": "OPME",
    "country_code": "BR",
    "agreement_code": "BRADESCO_xxx"
  }
}

Formato del error_code

071-<HTTP_STATUS>-<sufijo-opcional>

• 071 es el prefijo de DVS.
• <HTTP_STATUS> es el HTTP status code (por ejemplo, 403, 422).
• <sufijo-opcional> desambigua múltiples causas del mismo status.

Errores comunes

Status	error_code	Causa	Acción
401	071-401	Bearer token faltante o inválido	Refrescar token. Reintentar una vez.
403	071-403	Token válido pero sin la autoridad requerida	Revisar el scope al solicitar el token.
403	071-403-document-type-not-allowed	Provider no autorizado para esa combinación (doc_type, country, agreement)	Usar GET /v1/document-types para descubrir qué está permitido. Contactar a OSIGU si se necesita más acceso.
403	071-403-tenant-mismatch	Intentando leer un recurso de otro tenant	No hacer eso.
409	071-409-idempotency-mismatch	Misma Idempotency-Key usada con un body distinto	Usar una key nueva.
413	071-413-file-too-large	Archivo inline excede 3MB (sync) / 6MB (async)	Usar la variante con S3 URL o URL externa.
422	071-422	El body falló la validation	Inspeccionar additional_information. Corregir y reenviar.
422	071-422-agreement-required	Validation request con múltiples opciones de agreement	Reenviar con agreement_code explícito.
422	071-422-ssrf-blocked	URL externa apunta a una IP privada / host bloqueado	Usar una URL HTTPS pública.
422	071-422-unknown-document-type	document_type no está en el catálogo	Usar GET /v1/document-types para ver los slugs válidos.
429	071-429	Cuota diaria excedida	Esperar hasta medianoche UTC. additional_information.retry_after_seconds indica la espera exacta.
502	071-502-classifier-upstream	El motor de classification upstream falló tras los retries de DVS	Esperar y reenviar con Idempotency-Key nueva.
502	071-502-extraction-failed	El Document Processor falló tras los retries	Igual — esperar y reenviar.
504	071-504-sync-timeout	La classification sync excedió el presupuesto de tiempo	El recurso aún se está procesando. Hacer polling de GET /classification-requests/{id} con el id retornado.

Estrategia de retry

No reintentar 4xx (excepto 429)

Los errores 4xx indican un problema del cliente. Reintentar sin cambios producirá el mismo error. Corregir primero el request.

Reintentar 5xx con backoff exponencial

Usar 3 intentos: inmediato, +30s, +120s. Usar una Idempotency-Key nueva por seguridad.

En 429, respetar retry_after_seconds

El error incluye additional_information.retry_after_seconds. No reintentar antes de ese tiempo.

En 504, cambiar a polling

El recurso aún se está procesando. Obtener el classification_request_id del body del error y hacer polling de GET /classification-requests/{id} cada pocos segundos.

Fallas de red

Si el request nunca llega a DVS (timeout, reseteo de conexión), DVS pudo o no haberlo procesado. Usar Idempotency-Key en cada request para que los retries no dupliquen el trabajo.

Ver Idempotency para el patrón completo.