Rate Limiting

guides

Rate Limiting

Rate limiting caps how many requests a client can make in a given time window. Limits protect the API from abuse and ensure fair shared capacity. Exceeding a limit returns HTTP 429 Too Many Requests.

Common Limit Styles

  • Fixed window - N requests per calendar minute/hour.
  • Sliding window - N requests in any rolling period.
  • Token bucket - bursts allowed up to a bucket size, refilled at a steady rate.
  • Concurrency - maximum simultaneous in-flight requests.

Response Headers

Well-behaved APIs expose headers such as X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, and Retry-After. Read these on every response to adjust your throughput dynamically.

Handling 429 Responses

When you receive 429, do not retry immediately - that worsens congestion. Instead:

  1. Parse Retry-After (seconds to wait) if present.
  2. Otherwise use exponential backoff with jitter: wait 1s, 2s, 4s, 8s…
  3. Cap retries (e.g. 5 attempts) and surface a clear error if exhausted.
  4. Reduce your sustained request rate to stay under the limit.

Best Practices

  • Cache responses where possible to reduce call volume.
  • Batch endpoints to do more work per request.
  • Use queues to smooth bursts.
  • Monitor 429 rates and alert on spikes.
  • Upgrade your plan if you consistently hit limits.

Other languages