Too Many Requests

Overview

429 Too Many Requests means the client sent too many requests in a given window and hit a rate limit. The code protects the server from API abuse, excessive polling, and bot traffic.

A well-behaved server includes a Retry-After header (a delay in seconds or a date) and often RateLimit-* headers, telling the client how long to wait before retrying.

When it happens

• Exceeding an API's per-second or per-minute request limit
• A retry loop without backoff floods the server with requests
• Multiple instances sharing one API key split and exceed the limit

Request / Response example

GET /api/search?q=test HTTP/1.1
Host: api.example.com
Authorization: Bearer abc123

HTTP/1.1 429 Too Many Requests
Retry-After: 30
RateLimit-Remaining: 0
Content-Type: application/json

{"error":"rate_limited","retryAfter":30}

In code

async function fetchWithBackoff(url, tries = 5) {
  for (let i = 0; i < tries; i++) {
    const res = await fetch(url);
    if (res.status !== 429) return res;
    const wait = Number(res.headers.get('Retry-After') || 2 ** i);
    await new Promise(r => setTimeout(r, wait * 1000));
  }
  throw new Error('rate limited');
}

# Limit each client IP to 10 req/s, returning 429 on excess
limit_req_zone $binary_remote_addr zone=api:10m rate=10r/s;
location /api/ {
  limit_req zone=api burst=20 nodelay;
  limit_req_status 429;
}

Notes

• 429 is a transient error where retrying is valid — but retrying immediately makes it worse, so always add backoff.
• If there is no Retry-After, use exponential backoff to grow the wait time yourself between retries.
• When several workers share one key, each may look modest yet together exceed the limit — coordinate with a global rate limiter.

Related status codes

Related headers

Specification