document_unreadable (422)
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-dev.autohost-dev.uk/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-dev.autohost-dev.uk/api/errors/document_unreadable",
"details": {
"recognition_status": "FAILURE",
"id": "dvc_01HEXAMPLE0000000000000000"
}
}
}