Fix UPCS Error 429 rate_limited

The rate_limited error (HTTP 429) means the API key has made more requests in the current hour than it is allowed. Each key has an hourly limit, which is 1,000 requests per hour by default. Requests are accepted again once the limit period moves on.

Symptom

Requests that normally succeed return success: false with the code rate_limited, usually after a burst of traffic or a loop in your code.

Likely causes

• A script or import calls the API in a tight loop.
• The same lookup is repeated for every page view instead of being stored.
• Several sites or servers share one key.
• A failing integration retries immediately and repeatedly.

Fix it step by step

1. Pause the job or script that is making the requests.
2. Check your logs to see which endpoint and which page or task is generating the most calls.
3. Store results you already have. A code and its coordinates do not change, so keep them with the order or record instead of looking them up again.
4. Create one embed session per page load, not one per click or per refresh of the same page.
5. Add a delay and a limited number of retries to any automated retry logic. Do not retry instantly on a 429.
6. If several sites use one key, use a separate key for each site so one cannot use up the allowance of another.
7. Wait for the hourly window to pass, then resume.

Confirm it is fixed

Requests succeed again and your request count over the hour stays under the limit. If your traffic legitimately needs more than the default allowance, contact support and tell us the expected requests per hour.

Related errors

If requests fail with an authentication problem rather than a limit, see missing or invalid x-api-key or invalid or inactive key.