A field journal of third-party API failures, rate limits, breaking changes, and the postmortems teams wish they'd written sooner.

HTTP 429 Too Many Requests: What It Means and How to Handle It

What a 429 from a third-party API is telling you, why your integration is getting one, and how to retry without making it worse.

The Gateway Timeout · Updated

HTTP 429 Too Many Requests means the server received more requests from you than it is willing to handle in a given amount of time, and it rejected this one. It is the standard status code for rate limiting, defined in RFC 6585. It is not a bug in your request, and it is not the server falling over: the same request, sent later, is expected to work.

For an integration calling a third-party API, a 429 is a scheduling problem. The fix is never "send it again now". It is "send it again when the limit has room", and then "stop sending requests in a pattern that hits the limit".

What the standard says, and what it leaves to the provider

RFC 6585 keeps the definition short. A 429 response:

  • should explain the condition in its body, and
  • may include a Retry-After header saying how long to wait before making a new request.
  • must not be stored by a cache.

Everything else is deliberately left to whoever runs the API. The RFC does not say how the server identifies "the user" (an API key, an account, an IP address, an OAuth app, a workspace), how it counts requests, or over what window. That is why two APIs that both return 429 can need very different handling, and why the provider's own rate-limit page is the only authority on its numbers.

Anatomy of a 429 response

A typical rate-limited response from a JSON API looks something like this:

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

{
  "error": {
    "type": "rate_limit_error",
    "message": "Too many requests. Please retry after 30 seconds."
  }
}

Three parts of it carry information your client should read:

  1. Retry-After, defined in RFC 9110. Its value is either a number of seconds (Retry-After: 30) or an HTTP date (Retry-After: Wed, 18 Nov 2026 09:00:00 GMT). Parse both. When it is present, it is the best estimate you will get of when the limit has room again.
  2. Rate-limit headers, if the API sends them. Many APIs use vendor headers in the X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset style; an IETF draft, RateLimit header fields for HTTP, aims to standardise them but is still a draft. The meaning of "reset" varies between providers (a Unix timestamp in some, seconds remaining in others), so read the provider's docs before doing arithmetic on it.
  3. The error body. It often says which limit you hit, and sometimes that the 429 is not a rate limit at all (see below).

Not every API sends all three. Kalshi, for example, documents that its 429s currently carry no Retry-After or rate-limit headers at all, so a client has to estimate recovery itself; our Kalshi rate-limit guide walks through how.

Why your integration is getting 429s

In third-party integrations, most 429s come from a short list of patterns:

  • Bursts. A job that starts on the hour, a deploy that warms every cache at once, a backfill run in a tight loop. The average rate is fine; the peak is not.
  • Many workers, one budget. Limits are usually counted per account, key or token, not per process. Ten well-behaved workers sharing one key can exceed a limit none of them would hit alone. CI pipelines are a classic case: see rate limit behavior in shared CI token pools.
  • Retries that amplify. Clients that retry immediately, or on a fixed delay, all come back at the same moment and trip the limit again. Stacked retries across layers (SDK, HTTP client, job queue) multiply the effect. Exponential backoff and jitter covers why.
  • Per-endpoint and per-resource limits. Many APIs limit some methods more tightly than others, or limit per channel, per workspace or per object, so a client under its global limit can still be rejected. Slack's tiers are a good example: Slack API tier limits and burst behavior.
  • Concurrency limits. Some providers limit how many requests you have in flight at once, not just how many you send per second. Stripe's 429s, for instance, can come from rate limiters or concurrency limiters, and its Stripe-Rate-Limited-Reason header says which: see Stripe rate limit behavior across API versions.
  • Unauthenticated or IP-based limits. A request that loses its credentials (an expired token, a missing header in one code path) often falls under a much lower anonymous limit.
  • A proxy, not the API. A CDN, WAF or API gateway in front of the API, or in front of your own egress, can return its own 429 with its own rules. If the body or headers don't look like the provider's, check what actually answered.

When a 429 is not a rate limit

Because the status code is generic, some providers use 429 for conditions that waiting a few seconds will not fix, or that need different handling:

  • Exhausted quotas. Some APIs return 429 when a monthly, billing or plan quota is used up. OpenAI's API, for example, documents an insufficient_quota error that arrives as a 429. Retrying it just burns time; the error code in the body is what tells you.
  • Lock contention. Stripe returns 429 for lock timeouts on an object that another request is modifying, which is a different problem from a rate limit and needs different retry logic. Our Stripe rate-limit guide covers how to tell them apart.
  • Status codes other than 429. The reverse happens too: GitHub can answer an exceeded rate limit with 403 as well as 429, so code that only checks for 429 will miss it. See GitHub API rate limits for CI pipelines.

Classify by the error code and headers first, and the status code second. Differentiating retryable from non-retryable API errors goes through the full decision.

How to handle a 429 correctly

  1. Honour Retry-After when it is there. Wait at least that long before calling the same limit again. Don't shorten it, and don't let a generic backoff schedule override it.
  2. Otherwise back off exponentially, with jitter. Double the wait on each attempt up to a cap, and randomise it (full jitter, a random wait between zero and the computed delay, is a good default) so your workers don't retry in lockstep.
  3. Bound the retries. Cap the number of attempts and the total time spent, and fail the job visibly when the budget is gone. An unbounded retry loop turns a short rate limit into a long outage.
  4. Make writes safe to repeat. Most providers reject a rate-limited request before doing any work, but that is the provider's promise, not the status code's. Before re-sending a POST, check the provider's docs and use an idempotency key where it offers one.
  5. Retry in one layer only. Turn off automatic retries in either the SDK or your own wrapper, not both, so attempts don't multiply.
  6. Pause the whole client, not just the request. When one request gets a 429, the others sharing that key will get one too. Hold the shared queue until the wait is over.

A minimal TypeScript wrapper that does the first three:

function retryAfterMs(res: Response): number | null {
  const value = res.headers.get("retry-after");
  if (!value) return null;
  const seconds = Number(value);
  if (Number.isFinite(seconds)) return Math.max(0, seconds * 1000);
  const date = Date.parse(value); // HTTP-date form
  return Number.isNaN(date) ? null : Math.max(0, date - Date.now());
}

const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));

export async function fetchWithRateLimit(
  url: string,
  init: RequestInit = {},
  { maxAttempts = 5, baseMs = 500, capMs = 30_000 } = {},
): Promise<Response> {
  for (let attempt = 1; ; attempt++) {
    const res = await fetch(url, init);
    if (res.status !== 429 || attempt === maxAttempts) return res;

    const backoff = Math.random() * Math.min(capMs, baseMs * 2 ** (attempt - 1));
    await sleep(retryAfterMs(res) ?? backoff);
  }
}

It returns the last 429 to the caller once attempts run out, so the job can fail loudly instead of hanging. It does not check whether the 429 is a quota or lock error; add that check against your provider's error codes before you rely on it.

How to stop getting 429s in the first place

Handling 429s well keeps a rate limit from becoming an outage. Avoiding them keeps your integration fast:

  • Throttle on the client. Read the remaining-requests header on every response, not just failures, and slow down before it reaches zero. A token-bucket limiter sized below the provider's published limit works for steady traffic.
  • Share one limiter across workers. If processes share a key, they need a shared counter (in Redis, a database or a single dispatcher), not one limiter each.
  • Cap concurrency. A fixed-size worker pool protects you from concurrency limits that a requests-per-second limiter can't see.
  • Smooth scheduled work. Add a random offset to cron jobs and spread backfills over time.
  • Ask for less. Cache responses that don't change, use bulk or batch endpoints, request larger pages, and subscribe to webhooks instead of polling where the API offers them.
  • Know the real numbers. Limits differ between sandbox and production and between plans. Read them from the provider's rate-limit page for the account you run in production, and re-check them when you upgrade API versions.

How to test 429 handling

Live APIs won't produce a 429 on demand, and hammering one in CI to get one spends real budget and can get a key flagged. Static mocks that return a fixed 429 test the parsing, not the behaviour over a sequence of calls: the burst, the wait, the successful retry, the next burst.

What works is a fake that keeps state: it counts calls per key and per endpoint, returns 429 with the right headers when a threshold is crossed, and recovers on the provider's schedule. With one, you can assert that your client waited as long as Retry-After said, that workers paused together, and that a retried write did not happen twice. Testing retry logic without hitting live rate limits shows how to set one up.

429 and its neighbours

Status What it means Retry?
429 Too Many Requests You sent too many requests; the limit is yours. Yes, after Retry-After or a backoff. Check the error code for quota errors first.
503 Service Unavailable The server can't handle requests right now, for everyone. May also carry Retry-After. Yes, with backoff.
403 Forbidden You are not allowed to do this. Some APIs (GitHub among them) also use it for rate limits. Only if the body or headers say it is a rate limit.
504 Gateway Timeout A gateway or proxy didn't get a response from the server behind it in time. Carefully: the request may have been processed. Use idempotency keys for writes.

Frequently asked questions

Is a 429 error my fault or the server's?

It is a response to the rate at which your client sent requests, so the fix is on the client side: wait, then send fewer requests or spread them out. If you are only a user of a website or app showing "429 Too Many Requests", wait a few minutes and try again; it clears on its own.

How long should I wait after a 429?

As long as the Retry-After header says. Without it, start with a short backoff (around a second) and double it on each retry, with jitter and a cap. The provider's rate-limit page often says what window its limits use, which tells you the most you should need to wait.

Do rejected requests count against my rate limit?

It depends on the provider. Some count every request they receive, so a client that keeps retrying a 429 keeps itself limited. Check the provider's rate-limit documentation; if it doesn't say, assume they count.

Can I get a 429 from my own infrastructure?

Yes. An API gateway, load balancer, WAF or egress proxy can enforce its own rate limits and return 429. If the response doesn't match the provider's documented format, look at which hop sent it.

Sources

  1. RFC 6585, Additional HTTP Status Codes, section 4: 429 Too Many Requests
  2. RFC 9110, HTTP Semantics, section 10.2.3: Retry-After
  3. IETF HTTPAPI working group draft: RateLimit header fields for HTTP
  4. Stripe: Rate limits
  5. Slack: Web API rate limits
  6. GitHub: Rate limits for the REST API

Go deeper: Rate Limits and Throttling