Handle the UPCS API Rate Limit (429)

This page is for developers. It shows how to recognise and handle the hourly limit in your code. For the business view of the limit, see the hourly limit explained.

The limit

Each API key allows 1,000 requests per hour by default. The limit is per key, so all of your servers and plugins using that key share it.

What you receive

When the limit is reached, the API returns HTTP 429 and an error with the code rate_limited:

{
  "success": false,
  "message": "...",
  "code": "rate_limited"
}

The message text may vary. Match on the status 429 and the rate_limited code.

Handle it in code

1. Detect the 429 status.
2. Stop sending further requests with that key for a while rather than retrying immediately.
3. Retry later with increasing waits, for example 1, 2, 4 minutes, up to a reasonable cap.
4. Show the user a neutral message instead of a raw error.

async function callUpcs(url, options, attempt = 0) {
  const res = await fetch(url, options);
  if (res.status !== 429 || attempt >= 3) return res;
  await new Promise(r => setTimeout(r, 60000 * 2 ** attempt));
  return callUpcs(url, options, attempt + 1);
}

Stay under the limit

• Request a session once per page view, not once per map interaction.
• Store resolved codes with your records instead of resolving them again; see resolve coordinates.
• Use separate keys for separate sites; see naming and separating keys.
• Do not poll the API.

If you regularly reach the limit, review the traffic first, then use the contact page. The full list of responses is in error codes explained.