Server Fault is a question and answer site for system and network administrators. It's 100% free, no registration required.

Sign up
Here's how it works:
  1. Anybody can ask a question
  2. Anybody can answer
  3. The best answers are voted up and rise to the top

How do I configure nginx to return http status code 429 (Too Many Requests) instead of the default 503 (Service Unavailable) when throttling/rate limiting?

FYI, I'm using nginx as a reverse proxy with the HttpLimitReqModule. The draft spec for 429 status code is RFC6585.

This (closed) question on stackexchanged shows that it is possible to use the error_page directive. However, I don't want to return a 429 if there really is a server problem (not the customer hitting us too much) and the server should be returning 503 Service Unavailable.

Any suggestions?

share|improve this question
FYI, I've created an enhancement request for this feature as it isn't possible without mapping all 503s to 429s. – adambrod Mar 6 '13 at 14:55
up vote 11 down vote accepted

Good news, with Version 1.3.15

we have the "limit_req_status" and "limit_conn_status" directives. I just tested them on Gentoo Linux (note that you need to have the modules limit_req and limit_con compiled in).

With these settings I think you can achieve what you've asked for:

limit_req_status 429;
limit_conn_status 429;

I have verified this with a quick:

ab2 -n 100000 -c 55 "

On which most request failed after activating the directive due to the high request rate and the configured limit in nginx:

limit_req zone=api burst=15 nodelay;
share|improve this answer

Nginx itself never returns 503 in cases other than limit_req and limit_conn.

share|improve this answer
Ah, that's interesting. So you're saying that if I replace 503 with 429 using error_page, I'll never be telling customers Too Many Requests unless they really are sending too many requests? – adambrod Mar 1 '13 at 15:06
Yes, true, but with only one exception, that you don't have (proxy/factcgi/scgi/uwsgi)_intercept_errors enabled. – VBart Mar 1 '13 at 15:17
It is also possible that the app served by nginx would return 503, which makes it hard for the client to see is it connection limit from nginx or server error from the app. – bbaja42 Jan 11 at 11:43

Based on VBart's response and other comments, it is clear that the best option is to map 503 errors to 429s.

error_page 503 = 429 /too-many-requests.html

Since nginx (1.3.x) only uses 503 status codes for limit_req and limit_conn, this should be a fine approach.

share|improve this answer

Your Answer


By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.