FAQ
Troubleshooting FAQ: Fix Common UPCS Problems
Fixes for common UPCS problems: API errors 401, 403, 422 and 429, map not showing, plugin issues, wrong location, code not found and one-time code not received.
Updated 14 October 2026 · 4 min read
Most UPCS problems come down to an API key, an allowed origin, a supported country or a plugin setting. The answers below explain the documented errors and the usual fixes for the map, the plugins and sign-in. If you are still stuck, the contact page is the next step.
Frequently asked questions
Why is the UPCS map not showing on my page?
Common causes are a missing or expired session token, a page origin that is not registered under Allowed origins, or an inactive key. Check the browser console and the error returned by your session request.
Why do I get a 401 session_expired error?
The embed session token is missing, invalid or past its lifetime, which is 15 minutes by default. Create a new session on your server and mount the map again.
Why do I get a 401 key_inactive error?
The API key behind a running embed session was disabled or has expired, so the map can no longer make requests. Check the key in the partner panel and enable it or use another key, then create a new session. A direct server call with a disabled key returns a 401 with the message Invalid or inactive API key and no code.
Why do I get a 401 error about a missing or invalid API key?
The x-api-key header is absent, the value is wrong, or the key is disabled or expired. These 401 responses carry a message but no code. Confirm that the full key starting with upcs_ is sent with the request and that it is enabled in the partner panel.
What does the 403 partner_required error mean?
The API key you sent is not linked to a partner account, so a session cannot be created for it. Register a partner account on the partner page and use a key from its panel.
What does the 403 origin_not_allowed error mean?
The origin sent with your request is not registered under Allowed origins in the partner account that owns the key. Add the exact https origin of your site in the partner panel.
Why am I getting a 403 saying my IP is not allowed?
The key has an IP restriction and your request came from an address that is not allowed. The response is a 403 with no code. Make the request from an allowed server, or contact UPCS with the outgoing IP, since the partner panel does not manage IP restrictions.
Why do I get a 422 unsupported_location error?
The selected point, or the coordinates sent to the resolve endpoint, are outside the 25 countries UPCS supports. Choose a location inside a supported country and check that latitude and longitude are not swapped.
Why do I get a 422 validation error?
One of the values you sent is invalid, such as the origin, lat or lng. Check the format of each field and try again.
Why do I get a 429 rate_limited error?
The key has exceeded its hourly request limit, which is 1,000 requests per hour by default. Wait for the limit to reset and reduce unnecessary calls.
Why does the map work on localhost but not on my live site?
The live site's https origin must be registered separately under Allowed origins. Localhost is accepted only as http://localhost:5173 for development.
Why does the map stop working after I remove an origin or disable a key?
Removing an origin or disabling a key immediately stops the sessions that depend on it. Restore the origin or key and create a new session.
Why can't I see the grid on the map?
The grid appears only from zoom level 18. Zoom in further on the map to see the 3 m by 3 m cells.
The WordPress plugin says the API connection failed. What should I do?
Re-enter the API key under Settings, then UPCS Map, and press Test API Connection again. Also confirm that the key is active in the partner panel.
Why is the map missing from my WooCommerce checkout?
The checkout map needs WooCommerce and shows after the billing form of the classic checkout. Check that the plugin is activated, the API key is saved, your WordPress and PHP versions meet the requirements, and clear any page or asset cache.
The PrestaShop module does not show the map. What can I check?
Confirm the module is installed, Status is enabled, and it has a valid API key and a Display position that suits your theme. Your PrestaShop version should be 1.7.7 or newer, or you can place the map yourself with the widget call and the Manual position.
The OpenCart extension does not appear at checkout. What should I do?
Make sure the module is enabled and added to the Checkout layout under Design, then Layouts. The extension is for OpenCart 4.x.
Why is the location wrong or slightly off?
A UPCS code leads to the exact 3 m by 3 m cell that was picked, so if the spot looks different the point chosen was probably a cell nearby. Zoom in to the grid, select the exact cell you want and the new code will lead there.
Why does the lookup say my code was not found?
The lookup endpoint returns 404 for a code that does not exist, and 400 for a value that is not a valid code format. Check for typing mistakes and that the code follows the format CC-XXXX-XXXX with the country prefix, for example PK-1A2B-3C4D.
I did not receive my one-time code on WhatsApp. What can I do?
Check that the number is entered correctly with the country code and that WhatsApp is working on that phone. Wait a short while and request a new code. If it still does not arrive, contact UPCS through the contact page.
Where can I get help if my problem is not listed here?
Use the contact page on upcs.io and include the error code and message you received. The developer documentation also describes the API and embed script.