Skip to content
Ubhub Location Service
Rate limits

Guides

Rate limits

Each API key can make a fixed number of requests per minute. Every response tells you where you stand.

Limits

  • The default limit is 100 requests per minute per API key. Your current limit is shown on the dashboard; a key can have its own limit.
  • Windows are fixed and aligned to the clock: 12:00:00–12:00:59, 12:01:00–12:01:59, and so on. The count resets at the start of each minute.
  • Every authenticated request counts, including requests that end in an error (for example a 400 for an invalid parameter). Requests rejected for a missing or invalid key are not counted against any key.
  • Limits apply per key, not per account: two keys have two separate budgets.

Response headers

Every /v1 response from an authenticated request, including errors, carries these headers:

Rate-limit headers
HeaderMeaning
X-RateLimit-LimitRequests allowed in each one-minute window.
X-RateLimit-RemainingRequests left in the current window.
X-RateLimit-ResetWhen the current window ends, as a Unix timestamp in seconds.
Retry-AfterOnly on 429: seconds to wait before retrying.
Response headers
HTTP/1.1 200 OK
Content-Type: application/json
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1790230080
X-Request-ID: 21ca93219865458f9b027c782e5a27b3

Browsers can read these headers from cross-origin requests; the API exposes them through CORS.

When you hit the limit

Once the window is used up, requests fail with 429 Too Many Requests until it resets:

429 Too Many Requests
HTTP/1.1 429 Too Many Requests
Retry-After: 23
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1790230080

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests.",
    "details": {
      "limit": 100
    }
  }
}

Wait at least Retry-After seconds before trying again. Retrying immediately only adds more rejected requests.

Best practices

  • Read X-RateLimit-Remaining and slow down before it reaches zero, instead of waiting for 429s.
  • On 429, sleep until X-RateLimit-Reset (or for Retry-After seconds), then retry.
  • For other retryable errors use exponential backoff with jitter (for example 0.5 s, 1 s, 2 s) and a maximum number of attempts.
  • Debounce search-as-you-type (about 300 ms) and cancel superseded requests.
  • Cache results you look up repeatedly, such as the addresses of your own locations.
  • If you need a higher limit, use separate keys per application or contact the platform team.