Rate Limits and Backoff Strategy

Every UPCS API key has an hourly request limit, 1,000 requests per hour by default. When you exceed it the API responds with HTTP 429 and the code rate_limited. Well-behaved clients slow down and retry, they do not hammer.

Reduce requests first

The cheapest request is the one you do not make:

• Reuse an embed session until it nears expires_at, instead of creating one per page view.
• Cache lookups; a code always refers to the same cell.
• Validate coordinates before sending them.
• Avoid polling.

Exponential backoff with jitter

When you receive a 429, wait, then try again with progressively longer waits. Add random jitter so many workers do not retry at the same instant.

async function withBackoff(fn, maxAttempts = 5) {
  let delay = 500; // ms
  for (let attempt = 1; ; attempt++) {
    const res = await fn();
    if (res.status !== 429 || attempt === maxAttempts) return res;
    const jitter = Math.random() * 250;
    await new Promise(r => setTimeout(r, delay + jitter));
    delay *= 2;
  }
}

Do not assume particular response headers such as a retry hint are present; build your policy on the status code and your own timing.

What not to retry

Retrying 401 key errors, 403 origin_not_allowed or 422 validation errors wastes allowance. Fix the cause instead. The error codes reference tells you which are worth retrying.

For users

Show a friendly message such as "The map is busy, please try again in a moment" rather than a raw error. If retries are exhausted, let the customer continue with their ordinary address.

Watch your usage

Log each 429 and track how close you run to the hourly allowance; see monitoring and logging API usage. Retried writes should also be safe to repeat, as covered in idempotency for location API calls.