Rate limits

Every request increments two counters in Redis: a per-minute window and a per-day window. Both must pass for the request to proceed.

Per-plan quotas

Response headers

Every protected response carries:

X-RateLimit-Limit-Minute: 60
X-RateLimit-Remaining-Minute: 42
X-RateLimit-Limit-Day: 1000
X-RateLimit-Remaining-Day: 870

Use them to back off proactively instead of waiting for a 429.

When you exceed a window

You'll get an HTTP 429 with one of:

{
  "error": "rate limit exceeded (per minute)",
  "code": "RATE_LIMIT_MINUTE",
  "retry_after": 27,
  "request_id": "8f0e1c54-..."
}

{
  "error": "rate limit exceeded (daily quota)",
  "code": "RATE_LIMIT_DAY",
  "retry_after": 41203,
  "request_id": "8f0e1c54-..."
}

retry_after is in seconds. Sleep that long, then retry — or surface the limit to your users.

Demo endpoint

/v1/demo/suggest is rate-limited per client IP, not per key — 30 requests/minute. The same headers apply.

Tips

• Cache successful geocoding results client-side (place IDs are stable).
• Use ?sessionToken=... on /v1/suggest so a single autocomplete session charges as one billable request rather than per keystroke.
• For burst workloads, upgrade to PRO before the daily window resets.