Tratamento de Erros

Todas as responses de erro do DVS compartilham um envelope JSON comum:

{
  "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 do error code

071-<HTTP_STATUS>-<sufixo-opcional>

• 071 é o prefixo do DVS.
• <HTTP_STATUS> é o status code HTTP (por exemplo, 403, 422).
• <sufixo-opcional> distingue múltiplas causas para o mesmo status.

Erros comuns

Status	error_code	Causa	Ação
401	071-401	Bearer token ausente ou inválido	Renove o token. Faça retry uma vez.
403	071-403	Token válido, mas sem a authority necessária	Verifique o scope ao solicitar o token.
403	071-403-document-type-not-allowed	Provider não autorizado para essa combinação (doc_type, country, agreement)	Use GET /v1/document-types para descobrir o que é permitido. Entre em contato com a OSIGU caso precise de mais acesso.
403	071-403-tenant-mismatch	Tentativa de leitura de um recurso de outro tenant	Não faça isso.
409	071-409-idempotency-mismatch	Mesmo Idempotency-Key usado com body diferente	Use uma chave nova.
413	071-413-file-too-large	Arquivo inline excede 3MB (sync) / 6MB (async)	Use a variante de S3 URL ou external URL.
422	071-422	Body falhou na validação	Inspecione additional_information. Corrija e reenvie.
422	071-422-agreement-required	Validation request com múltiplas opções de agreement	Reenvie com agreement_code explícito.
422	071-422-ssrf-blocked	URL externa aponta para IP privado / host bloqueado	Use uma URL HTTPS pública.
422	071-422-unknown-document-type	document_type não está no catálogo	Use GET /v1/document-types para ver os slugs válidos.
429	071-429	Cota diária excedida	Aguarde até meia-noite UTC. additional_information.retry_after_seconds informa o tempo exato de espera.
502	071-502-classifier-upstream	Engine de classification upstream falhou após os retries do DVS	Aguarde e reenvie com Idempotency-Key novo.
502	071-502-extraction-failed	Document Processor falhou após retries	Idem — aguarde e reenvie.
504	071-504-sync-timeout	Classification sync excedeu o budget	Recurso ainda em processamento. Faça polling em GET /classification-requests/{id} com o id retornado.

Estratégia de retry

Não faça retry de 4xx (exceto 429)

Erros 4xx indicam problema no client. Refazer a request sem alterações produz o mesmo erro. Corrija a request primeiro.

Retry em 5xx com backoff exponencial

Use 3 tentativas: imediato, +30s, +120s. Utilize um Idempotency-Key novo por segurança.

Em 429, respeite retry_after_seconds

O erro inclui additional_information.retry_after_seconds. Não faça retry antes desse intervalo.

Em 504, mude para polling

O recurso ainda está sendo processado. Obtenha o classification_request_id do body do erro e faça polling em GET /classification-requests/{id} a cada poucos segundos.

Falhas de rede

Se a request nunca chegar ao DVS (timeout, connection reset), o DVS pode ou não ter processado. Use Idempotency-Key em toda request para que retries não dupliquem o trabalho.

Consulte Idempotency para o padrão completo.