Aaron Parecki

When running nginx as the front-end web service for your API, you may need to put up a "maintenance" page and send back "HTTP 503 Service Unavailable" for all incoming HTTP requests. For some reason, all the existing docs I found online were either too complicated or did not handle this properly. Here is a simple configuration block that will do the following:

• Return a header of HTTP 503 Service Unavailable
• Set the content-type to application/json
• Send a JSON file that you create as the response body

http {
  server {
    listen 80;
    server_name example.com;

    root /usr/local/nginx/html;

    location / {
      try_files $uri =503;
    }

    error_page 503 /maintenance.json;
  }
}

In the directory specified by root, create a maintenance.json file containing something like the following:

{
  "code": 503,
  "error": "temporarily_unavailable",
  "error_description": "Sorry, the service is temporarily unavailable"
}

After reloading nginx (something like /usr/local/nginx/sbin/nginx -s reload) all future requests to this host will return a response like below:

HTTP/1.1 503 Service Temporarily Unavailable
Server: nginx/1.4.7
Date: Thu, 04 Sep 2014 07:07:35 GMT
Content-Type: application/json
Content-Length: 128
Connection: keep-alive

{
  "code": 503,
  "error": "temporarily_unavailable",
  "error_description": "Sorry, the service is temporarily unavailable"
}