Failure Reasons

When validateNationalId() returns { isValid: false }, the result may carry a machine-readable reason (a ValidationFailureReason enum member) describing why validation failed (#117). parseIdInfo() reports the same reason for an invalid ID.

reason is best-effort and non-exhaustive: it's derived from each country's METADATA and validator, future minor releases may add new, more specific codes, and a value this table doesn't cover may still appear. Always handle unknown values, for example with a default branch in a switch.

Every reason code

unsupported_country, invalid_length, and invalid_format are derived the same way for every country, from METADATA.regexp/minLength/maxLength, so every country can report them.

checksum_mismatch needs a validator whose checksum() returns a definite boolean pass/fail for every candidate. Countries whose checksum() instead returns a computed check digit (a number) — or that have no checksum() at all — report a wrong digit as validation_failed.

invalid_birthdate needs a validator that checks the birth date its ID encodes, and reaches that check from validate() itself (see src/birthDateCheck.ts). A country whose validate() doesn't check the encoded date can't report it. Belgium (BEL) and Finland (FIN) were previously in this situation, but now check the encoded date from validate() as well (#205), and so do Bosnia and Herzegovina (BIH), China (CHN), Sri Lanka (LKA), North Macedonia (MKD), Montenegro (MNE), Serbia (SRB), and Slovenia (SVN) (#214). All of them match the Python library, which rejects such IDs too, apart from the Sri Lanka dates outside 0001-01-01 to 9999-12-31 noted below. Sri Lanka encodes a day of the year rather than a month and day. As in the Python library, a day number outside the year (day 000, or a day past the year's end) rolls into the adjacent year, so the ID stays valid. parseIdInfo() reports not_parsable for such an ID, and also for a year before 0100. Sri Lanka rejects year 0000, as Python does, and also rejects a date before 0001-01-01 or after 9999-12-31, where the Python library raises an error instead of returning a result.

The table below is re-derived by a test (issue-130-failure-reasons.test.ts), so it cannot drift from the validators; when a validator changes, the test prints the updated rows.

By country