Reference

Rate Limits

Every API key is subject to three rolling quotas — per minute, per day and per month. The limits come from your plan and can be overridden on individual keys.

Plan limits

Plan	Per minute	Per day	Per month
Free	30	200	1,000
Developer	300	5,000	50,000
Business	1,200	50,000	500,000
Enterprise	Unlimited	Unlimited	Unlimited

Response headers

Successful responses carry your current per-minute standing.

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 57
X-RateLimit-Reset: 1786531200

X-RateLimit-Reset is a Unix timestamp. On an unlimited plan, X-RateLimit-Limit is the string unlimited.

When you exceed a limit

The API responds 429 Too Many Requests and tells you which window you hit.

HTTP/1.1 429 Too Many Requests
Retry-After: 34

{
  "success": false,
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded: 60 requests per minute. Upgrade your plan or retry in 34 seconds.",
    "details": {
      "window": "minute",
      "limit": 60,
      "used": 60,
      "retry_after": 34
    }
  },
  "request_id": "9f1c…"
}

Handling 429 correctly

Respect Retry-After. It is the exact number of seconds until the window resets — no guessing needed.
Back off exponentially if you keep hitting the limit, rather than retrying in a tight loop.
Check details.window. A monthly limit will not clear in 34 seconds, and retrying will not help.
Rate-limited requests are still logged, so you can see the pattern in your dashboard.

Checking your quota

The status endpoint reports remaining quota without consuming a data call.

curl "https://address.s2coder.com/api/v1/status" \
  -H "X-API-Key: YOUR_API_KEY"

{
  "success": true,
  "data": {
    "key": "sk_addr_aB3x...9f2c",
    "name": "Production",
    "plan": "Developer",
    "status": "active",
    "limits": { "per_minute": 300, "per_day": 20000, "per_month": 50000 },
    "usage": { "month_to_date": 12840, "remaining_this_month": 37160 }
  }
}

Reducing your usage

Debounce autocomplete input rather than firing on every keystroke.
Cache PIN code lookups — that data is stable for months.
Use the smallest limit that satisfies your UI.
For bulk work, import your dataset and query it locally instead of looping over the API.

Previous Reverse Geocoding API Next Errors