HTTP 429 Too Many Requests

HTTP 429 Too Many Requests (RFC 6585) indicates the client has sent too many requests in a given time period (rate limiting). The server SHOULD include a Retry-After header telling the client when it can try again. This is the standard rate-limiting response — APIs use it to protect against abuse, enforce fair usage quotas, and prevent service degradation from excessive traffic.

Debug HTTP 429 live

Analyze real 429 behavior — headers, caching, CORS, redirects

Open Inspector →

Try it (live endpoint)

Response includes the status code, standard headers (including Content-Type), and a small diagnostic JSON body describing the request and returned status.

Simulator URL (copy in the app after load — not a normal link):

https://httpstatus.com/api/status/429

Example request:

curl -i "https://httpstatus.com/api/status/429"

Try in playground

Meaning

The user has sent too many requests in a given amount of time.

What it guarantees

The request was not fulfilled due to a client-side issue.
A rate/quota policy blocked the request.

What it does NOT guarantee

Retries will succeed without changing request inputs.
The server is healthy; it may still be failing for other reasons.

When to use this status

Per-IP or per-token throttling to protect the service.
Quota enforcement where clients must back off.
Abuse protection when requests must be slowed down.

When NOT to use this status (common misuses)

Using 400 for authentication/authorization failures.

Clients cannot distinguish validation vs auth; retry/login flows break.

Using 404 to mask permission issues everywhere.

Monitoring misclassifies access bugs; SEO can degrade if real pages appear missing.

Returning 4xx for server-side bugs.

Clients stop retrying; incidents are masked as client behavior.

Returning 429 without Retry-After/backoff guidance.

Retry storms amplify throttling and degrade availability.

Critical headers that matter

Content-Type

Defines error body format (JSON/text/problem+json).

Clients can’t parse structured errors; observability loses fidelity.

Cache-Control

Prevents caching transient errors unless intended.

CDNs cache failures; prolonged user-visible outages.

Retry-After

Tells clients when to retry safely.

Clients retry too aggressively; throttling becomes less effective.

Tool interpretation

Browsers

Displays an error state; devtools exposes status and headers. Cache headers can accidentally cache error documents.

API clients

Classifies as failure; retry policy depends on idempotency and code class. Structured errors improve handling.

Crawlers / SEO tools

Persistent failures reduce crawl rate; soft-404 patterns cause indexing instability.

Uptime monitors

Typically alerts based on rate/threshold. Consistent classification reduces false positives.

CDNs / reverse proxies

May cache errors if misconfigured; respects Cache-Control and can serve stale on origin failure.

Inspector preview (read-only)

On this code, Inspector focuses on semantics, headers, and correctness warnings that commonly affect clients and caches.

Signals it will highlight

Status semantics vs method and body expectations
Header sanity (Content-Type, Cache-Control, Vary) and evidence completeness
Error cacheability and retry guidance signals

Correctness warnings

Missing Retry-After increases retry storms and destabilizes clients.

Guided Lab outcome

Reproduce HTTP 429 Too Many Requests using a controlled endpoint and capture the full exchange.
Practice distinguishing status semantics from transport issues (redirects, caching, proxies).
Identify the minimum request changes required to move from client error to success.

Technical deep dive

HTTP 429 Too Many Requests has specific technical implications for API design, caching, and client behavior. Understanding the precise semantics helps distinguish it from similar status codes and implement correct error handling. The response should include a descriptive body following a consistent error schema (like RFC 7807 Problem Details) so clients can programmatically handle the error.

Real-world examples

REST API returning 429

A well-designed API returns 429 Too Many Requests with a structured error body containing the error type, human-readable message, and machine-readable code. The client uses this to display an appropriate error message or take corrective action.

Web application encountering 429

A web application receives 429 from an API call. The frontend error handler maps the status code to a user-friendly message and either prompts the user to correct their input, retry the request, or contact support.

Monitoring and alerting for 429

An observability system tracks 429 Too Many Requests responses. Client errors (4xx) are typically logged at WARN level since they indicate client issues, not server problems. Spikes in 429 responses may indicate a broken client deployment or API contract change.

Framework behavior

Express.js (Node)

Express: res.status(429).json({ error: 'Too Many Requests', message: 'Descriptive error' }). Custom error middleware: app.use((err, req, res, next) => { if (err.status === 429) res.status(429).json(err.body); });

Django / DRF (Python)

Django REST Framework handles 429 through exception classes. Custom: raise APIException(detail='Error message', code=429). DRF's exception_handler formats consistent error responses.

Spring Boot (Java)

Spring: throw new ResponseStatusException(HttpStatus.valueOf(429), "Error message"). Or use @ControllerAdvice to handle specific exception types and return 429 with structured error bodies.

FastAPI (Python)

FastAPI: raise HTTPException(status_code=429, detail='Error message'). Custom exception handler: @app.exception_handler(CustomError) to return 429 with structured error responses.

Debugging guide

Read the full response body — well-designed APIs include error details explaining why 429 was returned
Check request headers (Authorization, Content-Type, Accept) — many 429 errors stem from missing or incorrect headers
Compare your request against the API documentation — verify required fields, parameter types, and URL format
Use curl -v or httpie to reproduce the request and see the full HTTP exchange
Check server logs for additional context — the response body may be a sanitized version of a more detailed server-side error

Code snippets

Node.js

// Handle 429 Too Many Requests in Express
app.use((err, req, res, next) => {
  if (err.status === 429) {
    return res.status(429).json({
      type: 'https://api.example.com/errors/too-many-requests',
      title: 'Too Many Requests',
      status: 429,
      detail: err.message
    });
  }
  next(err);
});

Python

from fastapi import HTTPException

# Raise 429 Too Many Requests
raise HTTPException(
    status_code=429,
    detail={
        'type': 'too_many_requests',
        'message': 'Descriptive error for 429 Too Many Requests'
    }
)

Java (Spring)

// Spring Boot 429 Too Many Requests handling
@ExceptionHandler(CustomTooManyRequestsException.class)
public ResponseEntity<ErrorResponse> handleTooManyRequests(
        CustomTooManyRequestsException ex) {
    return ResponseEntity.status(429)
        .body(new ErrorResponse("Too Many Requests", ex.getMessage()));
}

// Return 429 Too Many Requests
func errorHandler(w http.ResponseWriter, message string) {
	w.Header().Set("Content-Type", "application/json")
	w.WriteHeader(429)
	json.NewEncoder(w).Encode(map[string]any{
		"status":  429,
		"error":   "Too Many Requests",
		"message": message,
	})
}

FAQ

What is the difference between 429 Too Many Requests and similar status codes?

429 Too Many Requests has specific semantics that distinguish it from other 4xx codes. Understanding these distinctions is crucial for proper API design and client error handling.

Should my API return 429 Too Many Requests or a different status code?

Use 429 when the error precisely matches Too Many Requests's definition. If the error is more general, consider 400 Bad Request. If it's about permissions, use 401/403. Always prefer the most specific status code that accurately describes the error.

How should clients handle 429 Too Many Requests?

Clients should: (1) read the response body for error details, (2) determine if the error is retryable, (3) take corrective action if possible (fix input, refresh auth, wait and retry), (4) display an appropriate message to the user.

How does 429 Too Many Requests affect monitoring and SLA calculations?

4xx errors are generally not counted against server-side SLAs since they indicate client errors. However, sudden spikes in 429 responses may indicate server-side issues (broken deployment, configuration change) even though they manifest as client errors.