UPCS Lookup Returns 404 for a Code

A 404 from GET /v1/upcs/lookup/{code} means UPCS does not know the code you asked about. Authentication worked; the code itself was not found.

Symptom

The lookup request returns HTTP 404 with success: false, or the lookup page on upcs.io shows that the code could not be found.

Likely causes

• A typo, such as a letter and a digit confused (0 and O, 1 and I).
• The code is incomplete or has extra characters, spaces or a trailing punctuation mark.
• The country prefix or the format is wrong. A UPCS code looks like PK-1A2B-3C4D: a two-letter country prefix and two blocks.
• The value is an official postal code, not a UPCS code. They are different things.
• The code was copied from a message that changed some characters.
• On the API, the code was never stored. The lookup endpoint finds stored codes, for example ones saved with save: true or created with the generate endpoint.

Fix it step by step

1. Compare the code character by character with the original source.
2. Make sure it has the format CC-XXXX-XXXX with hyphens and nothing around it.
3. Remove spaces and line breaks. Do not add quotation marks or URL parts.
4. Request the code exactly as shown, for example upcs.io/PK-1A2B-3C4D, or paste it into the search box at the top of the site.
5. If you only have coordinates, generate the code instead with POST /v1/upcs/generate, or choose the place on the map.
6. In code, URL-encode the path value and make sure you call the lookup endpoint with the x-api-key header.

Confirm it is fixed

The lookup returns the code, country, latitude and longitude and the map links. If the result is a real place but not the one you expected, see a code points to the wrong place.

When to contact support

If a code you received from UPCS itself returns 404, contact support with the code and where you got it.