> ## Documentation Index
> Fetch the complete documentation index at: https://docs.proofage.net/llms.txt
> Use this file to discover all available pages before exploring further.

# Decision reasons

> Reference for every ProofAge decision reason code: why a verification was declined or sent for resubmission, what each code means and how to handle it.

When a verification ends as `declined` or `resubmission_requested`, its `reason` field names why, in the [verification object](https://docs.proofage.net/api-reference/data-models.md#verification) and in the [webhook](https://docs.proofage.net/api-reference/webhook-decision.md). For every other status `reason` is `null`, and so is it on the `resubmission_requested` a facial age estimation sends when it asks for an ID.

A verification carries one reason: the most important of what went wrong. A selfie that is unclear and also looks like a photo of a screen is reported as the screen, not as unclear.

## Using the reasons

* **Declined** is final, whatever the code. Usually the check found something a new photo would not fix. But when the attempts run out, the verification is declined with the last attempt's reason, which may be a code from the retake family below. Never offer a retry on `declined`. Don't wait for `verification.attempts.exhausted` to spot a run-out either: it is listed below, but a verification that runs out of attempts carries its last attempt's reason.
* **Resubmission requested** means the person can still fix it. The widget already asks them to retake the image, so you rarely need to show the reason yourself.
* Map codes to your own messages where you need them, and treat a code you do not know as a generic failure: new codes are added as checks improve.
* The code's first segment tells you which step failed: `selfie`, `document`, `verification` (a rule about the whole verification) or `aml` (the blocklist). Document codes name the side next when it matters, as in `document.front.glare.high`.

## Face re-verification reasons

A [face re-verification](https://docs.proofage.net/integration/face-reverification.md) can end `declined` with `reference.face.mismatch` (the faces do not match) or `reference.unavailable` (after the session was created, the earlier verification was erased or reversed, or its face reached the end of its retention period). Both are final: there is no retry on the same verification. Its liveness and selfie reasons are the usual `selfie.*` ones.

## All reasons

### Blocklist

| Code | Label | What happened | Outcome |
| - | - | - | - |
| `aml.blocklist.device_match` | Device Linked to Blocked Identity | This device is linked to a blocked identity | Declined |
| `aml.blocklist.face_match` | Blocked by Security Policy | This person matches a restricted list | Declined |

### Document

| Code | Label | What happened | Outcome |
| - | - | - | - |
| `document.ai.image_manipulation` | Image Manipulation Detected | Signs of digital manipulation or editing were detected on the document image | Declined |
| `document.ai.not_a_document` | Not an Identity Document | The uploaded image does not appear to be a valid identity document | Declined |
| `document.ai.suspicious_words` | Suspicious Words Detected | Suspicious or anomalous text was detected on the document | Declined |
| `document.back.blur.high` | Back Image Blurred | The document back image is too blurry | Resubmission requested |
| `document.back.damaged.folded_over_text` | Document Folded (Back) | The document back is folded, obscuring important text | Resubmission requested |
| `document.back.damaged.torn_or_cut` | Document Torn or Cut (Back) | The document back is physically torn or cut | Resubmission requested |
| `document.back.data.not_readable` | Back Data Not Readable | Text on the document back cannot be read — the image may be too blurry, damaged, or poorly lit | Resubmission requested |
| `document.back.data.not_visible` | No Text Detected (Back) | No text was detected on the document back — the image may not contain a valid document | Resubmission requested |
| `document.back.framing.not_fully_in_frame` | Document Back Outline Not Found | The edges of the back of the document could not be located in the photo | Resubmission requested |
| `document.back.glare.high` | High Glare on Back | Excessive glare on the document back makes it hard to read | Resubmission requested |
| `document.back.not_a_document_suspected` | Not a Valid Document (Back) | The back image does not appear to be a valid identity document | Declined |
| `document.back.obscured` | Document Back Obscured | Part of the document back is covered or obstructed by an object | Resubmission requested |
| `document.back.quality.poor` | Poor Back Quality | The document back image quality is insufficient | Resubmission requested |
| `document.back.quality.screen_suspected` | Screen Photo Suspected — Retake (Back) | The document back may have been photographed from a screen; one retake was requested | Resubmission requested |
| `document.back.spoof.photo_suspected` | Photo of Photo Suspected (Back) | The document back appears to be a photograph of another photo | Declined |
| `document.back.spoof.print_suspected` | Printed Document Suspected (Back) | The document back appears to be a printed copy | Declined |
| `document.back.spoof.screen_suspected` | Screen Photo Suspected (Back) | The document back appears to be photographed from a screen | Declined |
| `document.back.tampering.suspected` | Document Tampering Suspected (Back) | The document back shows signs of potential tampering or alteration | Declined |
| `document.birth_date.conflict` | Date of Birth Does Not Match | The date of birth printed on the document is not the one in its machine-readable zone | Resubmission requested |
| `document.checks.not_provided` | Document Check Missing | Required document verification was not provided | Declined |
| `document.data.not_visible` | No Text Detected | No text was detected on the document — the image may not contain a valid document | Resubmission requested |
| `document.expired` | Document Expired | The identity document has passed its expiry date | Resubmission requested |
| `document.face.match_insufficient_quality` | Face Comparison Inconclusive | The document photo quality is insufficient for reliable face comparison — please retake the document photo with better lighting | Resubmission requested |
| `document.face.mismatch` | Face Does Not Match | The selfie does not match the document photo | Declined |
| `document.fields.required_missing` | Required Fields Missing | Essential document information could not be read | Resubmission requested |
| `document.front.blur.high` | Front Image Blurred | The document front image is too blurry | Resubmission requested |
| `document.front.damaged.folded_over_text` | Document Folded (Front) | The document front is folded, obscuring important text | Resubmission requested |
| `document.front.damaged.torn_or_cut` | Document Torn or Cut (Front) | The document front is physically torn or cut | Resubmission requested |
| `document.front.data.not_readable` | Front Data Not Readable | Text on the document front cannot be read — the image may be too blurry, damaged, or poorly lit | Resubmission requested |
| `document.front.data.not_visible` | No Text Detected (Front) | No text was detected on the document front — the image may not contain a valid document | Resubmission requested |
| `document.front.face.angle_incorrect` | Document Face Photo at Wrong Angle | The face photo on the document is tilted or at the wrong angle | Resubmission requested |
| `document.front.face.not_clear` | Document Face Photo Blurry | The face photo on the document is blurry or unclear | Resubmission requested |
| `document.front.face.not_found` | No Face on Document | No face photo was found on the front of the document | Resubmission requested |
| `document.front.face.occluded` | Document Face Photo Partially Hidden | Part of the face on the document is covered or obstructed | Resubmission requested |
| `document.front.face.too_small` | Document Face Photo Too Small | The face photo on the document is too small to extract for comparison | Resubmission requested |
| `document.front.framing.not_fully_in_frame` | Document Front Outline Not Found | The edges of the front of the document could not be located in the photo | Resubmission requested |
| `document.front.glare.high` | High Glare on Front | Excessive glare on the document front makes it hard to read | Resubmission requested |
| `document.front.not_a_document_suspected` | Not a Valid Document (Front) | The front image does not appear to be a valid identity document | Declined |
| `document.front.obscured` | Document Front Obscured | Part of the document front is covered or obstructed by an object | Resubmission requested |
| `document.front.quality.poor` | Poor Front Quality | The document front image quality is insufficient | Resubmission requested |
| `document.front.quality.screen_suspected` | Screen Photo Suspected — Retake (Front) | The document front may have been photographed from a screen; one retake was requested | Resubmission requested |
| `document.front.spoof.photo_suspected` | Photo of Photo Suspected (Front) | The document front appears to be a photograph of another photo | Declined |
| `document.front.spoof.print_suspected` | Printed Document Suspected (Front) | The document front appears to be a printed copy | Declined |
| `document.front.spoof.screen_suspected` | Screen Photo Suspected (Front) | The document front appears to be photographed from a screen | Declined |
| `document.front.tampering.portrait_replaced_suspected` | Portrait Replacement Suspected | The photo on the document appears to have been replaced | Declined |
| `document.front.tampering.suspected` | Document Tampering Suspected (Front) | The document front shows signs of potential tampering or alteration | Declined |
| `document.front.tampering.text_overlay_suspected` | Text Overlay Suspected (Front) | Text on the document front appears to be digitally overlaid | Declined |
| `document.quality.poor` | Poor Document Quality | The document image quality is insufficient | Resubmission requested |
| `document.sides.mismatch` | Front and Back Do Not Match | The front and the back appear to come from two different documents | Resubmission requested |
| `document.specimen.detected` | Specimen Document | The document is a published sample card, not an identity document issued to a person | Declined |

### Face re-verification

| Code | Label | What happened | Outcome |
| - | - | - | - |
| `reference.face.mismatch` | Face Does Not Match the Earlier Verification | The selfie does not match the selfie of the earlier verification | Declined |
| `reference.unavailable` | Earlier Verification Unavailable | The earlier verification was erased, reversed or holds no face to compare with | Declined |

### Selfie

| Code | Label | What happened | Outcome |
| - | - | - | - |
| `selfie.capture.not_attempted` | Selfie Not Captured With Camera | The selfie was not taken with the device camera during the verification session | Declined |
| `selfie.face.multiple_detected` | Multiple Faces Detected | More than one face was detected in the selfie | Resubmission requested |
| `selfie.face.not_clear` | Face Not Clear | The face in the selfie is blurry or unclear | Resubmission requested |
| `selfie.face.not_found` | Face Not Detected | No face was found in the selfie image | Resubmission requested |
| `selfie.face.occluded` | Face Partially Hidden | Part of the face is covered or obstructed | Resubmission requested |
| `selfie.framing.not_fully_in_frame` | Face Not Fully Visible | The face is cut off or not fully in frame | Resubmission requested |
| `selfie.liveness.failed` | Liveness Check Failed | The liveness check did not confirm a live person in front of the camera | Declined |
| `selfie.liveness.incomplete` | Liveness Check Incomplete | The liveness check could not be completed on this device or connection | Resubmission requested |
| `selfie.liveness.not_completed` | Liveness Check Not Completed | The person did not complete the requested head movement within the allowed tries | Resubmission requested |
| `selfie.liveness.unavailable` | Liveness Check Unavailable | The liveness check could not be completed for technical reasons | Declined |
| `selfie.quality.lighting_poor` | Poor Lighting | The selfie has insufficient or uneven lighting | Resubmission requested |
| `selfie.quality.poor` | Poor Image Quality | The selfie quality is insufficient for verification | Resubmission requested |
| `selfie.quality.screen_attack_suspected` | Screen or Device Check Failed | Please retake the selfie without screens or other devices visible | Resubmission requested |
| `selfie.quality.spoof_suspected` | Selfie Liveness Check Failed | Please retake the selfie directly from a live face | Resubmission requested |
| `selfie.quality.too_bright` | Image Too Bright | The selfie is overexposed | Resubmission requested |
| `selfie.quality.too_tilted` | Face Angle Incorrect | The face is tilted or at the wrong angle | Resubmission requested |
| `selfie.spoof.non_human_suspected` | Non-Human Face Suspected | The selfie face appears to be a doll, figurine, mannequin or mask rather than a live person. | Declined |
| `selfie.spoof.print_suspected` | Printed Photo Suspected | The photo appears to be of a printed image | Declined |
| `selfie.spoof.screen_suspected` | Screen Photo Suspected | The photo appears to be taken from a screen | Declined |

### Verification

| Code | Label | What happened | Outcome |
| - | - | - | - |
| `verification.age_threshold.failed` | Age Requirement Not Met | The person does not meet the minimum age requirement | Declined |
| `verification.attempts.exhausted` | Attempts Exhausted | All resubmission attempts have been used without a successful verification | Declined |
| `verification.processing.failed` | Processing Error | An error occurred during verification processing | Resubmission requested |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.