Is it possible to change the HTTP status code returned when proxy_pass gateway is down in nginx?

Question

For SEO purposes, we would like to change the HTTP status code returned whenever the backend machine behind nginx goes down for some reason.

We would like to change this to "503 Service Unavailable". As well as provide a Retry-After header to indicated to Google / Bing that the request should be retried in X number of seconds.

Is this possible via nginx?

I am not talking about a custom error page, but rather the status code returned in the header.

Answer 1

I think you will have to set up a specific error page, however you can achieve what you're looking for if you do. Try this:

location / {
    proxy_pass http://backend;
    proxy_intercept_errors on;
    error_page 502 503 504 =503 @proxyisdown; # always reply with 503
}

location @proxyisdown {
    add_header Retry-After 500 always;
    index my_pretty_error_page.html; 
}

If you work it this way you should be able to return the 503 (that's the =503 part of the error_page directive) and retry-after headers with the benefit that your visitors will receive a nicely formatted "oops, we're currently experiencing problems, try again in a few minutes" page rather than a blank "503 you don't really know what this means" page. :)

Answer 2

Name your error page /500.html and:

error_page 400 404 500 502 504 =503 /500.html;

# Optional if your public root is set above and the same for error pages,
# I sometimes please them outside the app, which is why I'm including it.
location /500.html {
  root /path/to/public;
}

Should work as well and seems a bit simpler to me. Note: it doesn't support the Header either.