Handling the unsupported_location Error

When a location falls outside the countries UPCS covers, the API responds with HTTP 422 and the code unsupported_location. It is not a fault in your integration. It is an expected case that you should handle deliberately.

The response

{
  "success": false,
  "message": "Location is outside supported coverage",
  "code": "unsupported_location"
}

The message text above is illustrative. Branch on the code, not the wording.

Supported countries

UPCS currently supports 25 countries: Pakistan, United States, India, China, Brazil, Australia, Canada, United Kingdom, Germany, France, Italy, Spain, Japan, Mexico, Russia, Argentina, South Africa, Nigeria, Egypt, Turkey, Iran, Saudi Arabia, United Arab Emirates, Thailand and Vietnam. A point outside these countries returns this error.

Where you may see it

• Resolve calls from your server (a generate call may also reject unsupported points).
• A selection on the embedded map, via the onError callback (it receives status, code and message).

How to handle it

1. Do not retry; the answer will not change for the same point.
2. Do not log it as a system error. Count it as a normal outcome.
3. Tell the user plainly: "UPCS codes are not available at this location. Please use your address as usual."
4. Let the order continue. The code is optional and complements the address.

try {
  const data = await resolve(lat, lng);
  saveLocation(data);
} catch (err) {
  if (err.code === 'unsupported_location') {
    showNotice('A UPCS code is not available here. Please enter your address.');
  } else {
    throw err;
  }
}

Avoid it up front

If your business only ships to certain countries, compare the customer's chosen country against the supported list before calling the API. This saves requests against your hourly limit; see rate limits and backoff. It will not catch every case, since a valid-looking coordinate can still be outside coverage; see validating coordinates.

All error responses are listed in the error codes reference.