Reason codes
Stable machine codes explaining why a check did not approve
A reason code says why a check produced something other than approve. They are stable, upper snake
case strings, they appear on the check that produced them and on the verification as a whole, and
they are the right thing to branch on when you decide what to tell a user.
They are additive. New codes can appear at any time, so always have a default branch that shows generic guidance rather than throwing on an unrecognised code.
Liveness
| Code | Meaning |
|---|---|
LIVENESS_FAILED | The capture did not evidence a real, present person. |
LIVENESS_LOW_CONFIDENCE | Inconclusive. Usually poor lighting or an obscured face. |
Face match
| Code | Meaning |
|---|---|
FACE_MATCH_BELOW_THRESHOLD | The selfie and the document portrait are not the same person. |
FACE_MATCH_BORDERLINE | Inconclusive. Worth a human look rather than an automatic decline. |
Document
| Code | Meaning |
|---|---|
MRZ_CHECKSUM_INVALID | The machine-readable zone failed its own integrity check. |
DOCUMENT_IMAGE_QUALITY_LOW | Readable enough to process, not clean enough to be sure. |
Age
| Code | Meaning |
|---|---|
AGE_BELOW_MINIMUM | The person is below the age the flow requires. |
AGE_ESTIMATE_UNCERTAIN | The estimate straddles your threshold. |
Screening
| Code | Meaning |
|---|---|
AML_SANCTIONS_HIT | The identity matched sanctions or watchlist data. |
AML_PEP_MATCH | The identity matched politically exposed person data. |
Proof of address
| Code | Meaning |
|---|---|
ADDRESS_MISMATCH | The document does not evidence the address claimed. |
ADDRESS_DOCUMENT_STALE | The document is older than the flow accepts. |
Turning codes into copy
Codes fall into two groups, and the distinction matters more than the individual code.
Some describe a capture problem, where the person is probably fine but the submission was not.
DOCUMENT_IMAGE_QUALITY_LOW, LIVENESS_LOW_CONFIDENCE and FACE_MATCH_BORDERLINE are all in this
group. Invite the user to try again with specific guidance, better light, a flat surface, no glare.
Others describe a substantive failure, where retrying will not help. AGE_BELOW_MINIMUM and
AML_SANCTIONS_HIT are in this group. Do not invite a retry, and be careful about how much detail
you reveal, since telling someone precisely which screening list they matched is rarely appropriate.
Do not echo raw codes to users
Reason codes are machine strings for your logic, not user-facing copy. Map them to your own wording, in your own tone, in the user's language.