How to Fix Nginx Rate Limiting Throwing 503 Instead of 429 to End Users

You've set up Nginx's rate limiting to protect an endpoint from abuse, and it's working — but rate-limited clients see a 503 Service Unavailable instead of the more accurate 429 Too Many Requests. This is simply Nginx's default behavior, not a bug, and it's a one-line configuration fix once you know the specific directive.

The Problem

A client exceeding your configured rate limit gets blocked, but with a status code that doesn't accurately describe why:

$ for i in {1..20}; do curl -s -o /dev/null -w "%{http_code}\n" https://yourapp.com/api/data; done
200
200
200
503
503
503

503 tells clients (and their retry logic, monitoring, and load balancers) that the service itself is unavailable — a very different, more alarming signal than "you're sending requests too fast," which is what 429 specifically communicates.

Why It Happens

Nginx's rate limiting modules — limit_req for request rate and limit_conn for concurrent connections — both default to returning a 503 status code when a client exceeds the configured limit, a default that predates 429 becoming a standard HTTP status code specifically meant for this exact situation (429 was formalized in RFC 6585 in 2012, well after Nginx's rate limiting modules were originally designed). Nginx never changed this default for backward compatibility reasons, so unless explicitly configured otherwise, every rate-limited request looks identical to a genuine server outage from the client's perspective. This matters in practice because:

• Client-side retry logic often treats 503 as "the server is down, back off significantly and retry later" versus 429's more specific "you personally are being throttled, slow down your own request rate" — conflating the two can cause client retry behavior that doesn't actually help the situation.
• Monitoring and alerting systems frequently treat 503 rates as a service health signal, and rate-limited traffic showing up as 503s can trigger false alarms about genuine outages when the service is actually healthy and functioning as designed.
• API consumers checking for a 429 specifically to implement proper backoff logic won't recognize a 503 as a rate-limit signal at all, potentially retrying in a way that makes the situation worse rather than better.

The Fix

Explicitly set the status code Nginx returns when the rate limit is exceeded, using limit_req_status for request-rate limiting:

http {
    limit_req_zone $binary_remote_addr zone=api_limit:10m rate=10r/s;

    server {
        location /api/ {
            limit_req zone=api_limit burst=20 nodelay;
            limit_req_status 429;
            proxy_pass http://127.0.0.1:3000;
        }
    }
}

For connection-count limiting specifically (as opposed to request rate), the equivalent directive is limit_conn_status:

http {
    limit_conn_zone $binary_remote_addr zone=conn_limit:10m;

    server {
        location /api/ {
            limit_conn conn_limit 5;
            limit_conn_status 429;
            proxy_pass http://127.0.0.1:3000;
        }
    }
}

Reload Nginx and verify the status code changed:

sudo nginx -t
sudo systemctl reload nginx

$ for i in {1..20}; do curl -s -o /dev/null -w "%{http_code}\n" https://yourapp.com/api/data; done
200
200
200
429
429

For a more complete, spec-compliant response, also add a Retry-After header telling clients how long to wait before retrying, which well-behaved HTTP clients and libraries will respect automatically:

location /api/ {
    limit_req zone=api_limit burst=20 nodelay;
    limit_req_status 429;

    add_header Retry-After 5 always;
    proxy_pass http://127.0.0.1:3000;
}

Consider also providing a custom error page for the 429 response with a clear, helpful message rather than relying on Nginx's bare default error page, especially for a public-facing API where clear communication about rate limits improves the integration experience for API consumers:

location /api/ {
    limit_req zone=api_limit burst=20 nodelay;
    limit_req_status 429;
    error_page 429 /429.json;
    proxy_pass http://127.0.0.1:3000;
}

location = /429.json {
    internal;
    default_type application/json;
    return 429 '{"error": "rate_limit_exceeded", "message": "Too many requests, please slow down."}';
}

Still Not Working?

If you've set limit_req_status 429 but still see 503s under specific conditions, check whether the 503s are actually coming from a different source entirely — a separate limit_conn directive without its own explicit status override, or genuine backend unavailability unrelated to rate limiting at all:

grep -rn "limit_req_status\|limit_conn_status\|limit_req \|limit_conn " /etc/nginx/

This surfaces every rate-limiting-related directive across your configuration, making it easy to spot a limit_conn block that's missing its own limit_conn_status 429 override alongside an already-corrected limit_req_status, since the two are configured independently and both need to be set for full consistency across every type of Nginx-enforced limit.