postcode_not_found
The postcode is well formed but is not in the directory
The postcode matches the country's pattern, and the whole postcode directory for that country is installed, and this code is not in it.
- appears in
- reason
- credits
- Free. An address that cannot stand as written never costs a credit.
What it means
Only a country whose complete directory Spaw carries can say a postcode does not exist; everywhere else an unknown code is simply not checked, and `postcode_status` answers null. The directory is named in `sources` with the version that answered.
A code the directory leaves out by design is never refused either. In Great Britain that is a Northern Irish BT postcode (left out of the installed directory for its licence), a BFPO number, a BF1 code and a non-geographic BX code: each answers `postcode_status: null`, not evaluated, with no town or county comparison.
Nor is the code of a box or forces address refused by a directory that lists places rather than every delivery code: a German Postfach PLZ or an APO ZIP the GeoNames copy lacks answers `postcode_status: null`. The British directory lists box and large-user codes, and the French copy carries La Poste's business codes, so those two still refuse a box code they lack. A ZIP+4 is looked up by its ZIP, the first five digits.
A code that was withdrawn is a different answer: a terminated postcode still exists in the directory, so the address stays valid and carries `postcode_status: "terminated"` with the `terminated_postcode` risk signal. `postcode_not_found` means the code was never issued, which is almost always a typo — a transposed pair, a letter O for a zero.
What to do
Treat it as a typo and ask for the postcode again. If you believe the code is current, the directory version in `sources` says which copy answered; a code issued since that copy was published is not in it yet.
Example response
{
"valid": false,
"reason": "postcode_not_found",
"country": "GB",
"postal_code": "NW1 6XF",
"postal_code_valid": true,
"postcode_status": null,
"risk_score": null
}Abbreviated: a real answer carries every field, listed in the validate-phone reference.
Related
- empty_address · nothing in the request was an address
- unknown_country · no postal format is published for that country
- missing_street · the country requires a street line and none was found
- missing_locality · a country with no postcode to name the town was given neither
- missing_administrative_area · a country with no postcodes needs the state or province
- missing_postal_code · the country requires a postcode and none was given
- invalid_postal_code · the postcode is not the shape that country uses
- All verdict reasons
- Phone fields and the risk score
- API reference
markdown version: /docs/reasons/postcode_not_found.md