NGINX rate limiting returns 503 not 429: limit_req_status explained

When limit_req rejects a request, nginx returns 503 by default. This is the same code used for genuine capacity exhaustion, so a 503 spike pages the on-call rotation even when the upstream is healthy and the infrastructure is fine. Changing limit_req_status to 429 is one directive, but the implications for alerting, monitoring, and client behavior are not trivial.

What it is and why it matters

The limit_req_status directive sets the HTTP status code returned when limit_req rejects a request. The companion directive limit_conn_status does the same for connection limits enforced by limit_conn. Both default to 503.

In HTTP semantics, 503 means the server is unable to handle the request due to temporary overload or maintenance. It implies infrastructure distress. 429 Too Many Requests means the client should back off. Rate limiting is a policy decision, not a capacity failure. Using 503 conflates the two.

For operators, a 503 spike demands differential diagnosis: upstream failure, application error, or a single aggressive client? Without per-location status breakdowns or error log inspection, you cannot tell from the code alone. For clients, a 503 often triggers immediate retry or failover, which is the wrong reaction to a rate limit. A 429 signals backoff.

How it works

The limit_req module tracks request rates in a shared memory zone defined by limit_req_zone. Each request checks the zone state for its key, commonly $binary_remote_addr. If the request exceeds the configured rate and burst, nginx returns the status defined by limit_req_status in the matching context. If the directive is absent, the code is 503.

The directive is valid in http, server, and location contexts and follows normal nginx inheritance. A setting in the http block applies to all locations unless overridden. This matters when only some paths are rate limited or when different locations need different rejection semantics.

Connection limiting via limit_conn works similarly. It enforces a maximum number of concurrent connections per key using a shared memory zone. When the limit is exceeded, nginx returns the status defined by limit_conn_status, which also defaults to 503. If you change one, change both to keep observability consistent.

The rejection happens before the request reaches the upstream. For proxied traffic, no upstream connection is opened and $upstream_response_time is not populated. The access log shows the 503 or 429 with no $upstream_addr or $upstream_status to provide context.

flowchart LR
    A[Request arrives] --> B{limit_req zone}
    B -->|Within limit| C[Process normally]
    B -->|Over limit| D[Return limit_req_status]
    D -->|Default| E[503 Service Unavailable]
    D -->|Custom| F[429 Too Many Requests]
    C --> G[Proxy or serve content]

Where it shows up in production

Monitoring and alerting confusion. Production alerting rules usually treat 5xx as server-side failure. A threshold like “page on 5xx rate > 1%” fires during rate limiting even when the infrastructure is behaving correctly. If rate limiting is first-line defense against abuse, you get paged for every bot or flash crowd. Setting limit_req_status 429 moves these rejections into 4xx, keeping 5xx alerts focused on genuine failures.

Client behavior and retry logic. API clients, load balancers, and service meshes often treat 503 and 429 differently. A 503 can trigger immediate retry on the next replica, spreading the rate-limited load across the cluster instead of backing off. A 429 signals the client to slow down. Returning 503 for rate limits causes well-behaved clients to misinterpret the signal and retry.

Incident correlation during partial outages. When an upstream fails, nginx marks it unavailable after max_fails consecutive errors. This produces 502 or 504 responses. If your metrics show a 503 spike, you must still rule out rate limiting before concluding it is an upstream issue. Without limit_req_status 429, you must correlate against error logs, upstream response times, and stub_status metrics to distinguish the two. This adds minutes to diagnosis during an incident.

Shared memory zone exhaustion. The more dangerous failure mode is limit_req_zone filling up. When the zone runs out of space for new tracking keys, nginx logs could not allocate node and stops enforcing rate limits for new clients. Existing keys continue to be tracked, but new keys pass through unchecked. Clients see normal responses, not 503 or 429. If your monitoring depends on rejection rates, you will not notice the rate limiter has disappeared until the upstream is overwhelmed.

Tradeoffs and common misuses

Setting limit_req_status 429 is not always a pure win. Some operators prefer 503 because it is less informative to attackers. A generic 503 does not confirm that rate limiting is in force; a 429 confirms the policy and gives precise feedback about the boundary. In most environments, the operational clarity of 429 outweighs this concern, but it is a factor for internet-facing endpoints under active attack.

Do not set limit_req_status 429 globally if you also use error_page 503 to serve maintenance pages or cached fallback content. The error_page directive intercepts responses by status code. If you change rate limiting to return 429, maintenance pages tied to 503 will no longer catch rate-limited requests. This is usually desirable, but verify your configuration before deploying.

Be careful with nested contexts. If you set limit_req_status 429 in a server block but have a location block with its own limit_req directive and no limit_req_status, the location inherits 429 from the server level. This is usually fine, but if some locations intentionally need different behavior, override explicitly.

If you use limit_req with nodelay, requests in excess of the burst are rejected immediately. Without nodelay, requests are delayed. Delayed requests that eventually succeed do not trigger limit_req_status. The status code only applies to rejected requests. Understand whether your configuration delays or rejects before relying on the status code as a signal.

Signals to watch in production

SignalWhy it mattersWarning sign
503 rate by locationDistinguishes upstream failure from rate limiting when limit_req_status is defaultSustained 503s from locations with limit_req but no upstream connect or timeout errors
429 rate (if configured)Measures intentional policy rejections cleanlySpike correlating with traffic increase, scan, or flash crowd
Error log limiting requestsConfirms the 503/429 spike is from rate limiting, not upstream failureEntries matching the time window of the status code spike
Error log could not allocate nodeIndicates limit_req_zone or limit_conn_zone exhaustionAny occurrence means new keys bypass limits silently
Active connections / Writing stateConnection limiting (limit_conn) defaults to 503, creating the same ambiguityHigh active connections with 503 responses and no upstream errors
Requests per second vs. rejected rateValidates whether limits are too tight for legitimate trafficRejection rate > 5% of total requests sustained

How Netdata helps

  • Correlate 503 spikes with upstream response time and error log patterns. If 503s appear while upstream response time is normal and the error log shows no upstream failures, the cause is likely rate limiting.
  • Access log status code distributions split 429 from 5xx. A surge in 429s after configuring limit_req_status 429 becomes a standalone signal that does not pollute the 5xx error rate.
  • Error log monitoring for limiting requests, limiting connections, and could not allocate node catches both active rate limiting and silent zone exhaustion.
  • stub_status active connections and the Reading/Writing/Waiting breakdown. High active connections with a 503 spike and normal upstream metrics point to limit_conn rather than upstream failure.
  • Shared memory zone exhaustion disables rate limiting without changing response codes. Alert on allocation errors in the error log; there is no status code signal for this failure mode.