> ## 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

> Every reason code a declined or resubmitted verification can carry, and what it means.

When a verification ends as `declined` or `resubmission_requested`, its `reason` field names why, in the [verification object](/api-reference/data-models#verification) and in the [webhook](/api-reference/webhook-decision). 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`.

## 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.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.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.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 |

### Selfie

| Code | Label | What happened | Outcome |
| - | - | - | - |
| `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.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.