Handle Errors

All DVS error responses share a common JSON envelope:

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

Error code format

071-<HTTP_STATUS>-<optional-suffix>

• 071 is the DVS prefix.
• <HTTP_STATUS> is the HTTP status code (e.g., 403, 422).
• <optional-suffix> disambiguates multiple causes of the same status.

Common errors

Status	error_code	Cause	Action
401	071-401	Missing or invalid Bearer token	Refresh token. Retry once.
403	071-403	Token valid but lacks required authority	Check scope when requesting token.
403	071-403-document-type-not-allowed	Provider not authorized for that (doc_type, country, agreement)	Use GET /v1/document-types to discover what's allowed. Contact OSIGU if you need more access.
403	071-403-tenant-mismatch	Trying to read another tenant's resource	Don't.
409	071-409-idempotency-mismatch	Same Idempotency-Key used with different body	Use a fresh key.
413	071-413-file-too-large	Inline file exceeds 3MB (sync) / 6MB (async)	Use S3 URL or external URL variant.
422	071-422	Body failed validation	Inspect additional_information. Fix and resubmit.
422	071-422-agreement-required	Validation request with multiple agreement options	Resubmit with explicit agreement_code.
422	071-422-ssrf-blocked	External URL points to a private IP / blocked host	Use a public HTTPS URL.
422	071-422-unknown-document-type	document_type not in catalog	Use GET /v1/document-types to see valid slugs.
429	071-429	Daily quota exceeded	Wait until midnight UTC. additional_information.retry_after_seconds gives the exact wait.
502	071-502-classifier-upstream	Classification engine upstream failed after DVS retries	Wait and resubmit with fresh Idempotency-Key.
502	071-502-extraction-failed	Document Processor failed after retries	Same — wait and resubmit.
504	071-504-sync-timeout	Sync classification exceeded budget	Resource still processing. Poll GET /classification-requests/{id} with the returned id.

Retry strategy

Don't retry 4xx (except 429)

4xx errors indicate a client problem. Retrying without changes will produce the same error. Fix the request first.

Retry 5xx with exponential backoff

Use 3 attempts: immediate, +30s, +120s. Use a fresh Idempotency-Key to be safe.

On 429, respect retry_after_seconds

The error includes additional_information.retry_after_seconds. Don't retry before that.

On 504, switch to polling

The resource is still being processed. Get the classification_request_id from the error body and poll GET /classification-requests/{id} every few seconds.

Network failures

If your request never reaches DVS (timeout, connection reset), DVS may or may not have processed it. Use Idempotency-Key on every request so that retries don't duplicate work.

See Idempotency for the full pattern.