document_unreadable (422)

← Error reference

document_unreadable

HTTP status: 422

Retryable: No. Retrying without changes will fail the same way.

The uploaded document image could not be read by the ID scan API.

When it fires

A `POST /v1/id-verification` request supplied an image the ID scan API could not read. The front may be too blurry, cropped, glare-obscured or low-resolution, or may not be a supported document. A `back` that you sent may also be unreadable: this fails the scan even when the front is clear. The scan also fails when no name, date of birth or document number could be read. The response carries `details.recognition_status: "FAILURE"` and the `dvc_...` call id for correlation. An unreadable document is not charged. The response does not say which cause applied.

How to handle it

Capture a clearer, well-lit, in-focus image of the full front of a supported document: a passport, driver's license, national ID card, residence permit, visa or work permit. If you sent a `back`, capture a clearer one or leave it out, because `back` is optional for every document. This is not a transient error. An identical retry of the same image yields the same result, so re-prompt for a better capture rather than retrying the same bytes. Within 24 hours, a retry with the same `Idempotency-Key` does not read the document again: a byte-identical request replays this response, and a rebuilt multipart body gets `409 idempotency_conflict`. Either way, send a new `Idempotency-Key` with the new images.

Example response

{
  "error": {
    "type": "https://docs.checktiv.com/api/errors/document_unreadable",
    "code": "document_unreadable",
    "message": "The document could not be read. Send a clear, well-lit image of the front of a supported ID document. If you included a back image, send a clearer one or leave it out.",
    "request_id": "req_01HEXAMPLE0000000000000000",
    "doc_url": "https://docs.checktiv.com/api/errors/document_unreadable",
    "details": {
      "recognition_status": "FAILURE",
      "id": "dvc_01HEXAMPLE0000000000000000"
    }
  }
}