Aaron Parecki

  • Articles
  • Notes
  • Photos
  • Setting a custom json 503 error page in nginx with proper http and content-type headers

    September 3, 2014

    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"
    }
    
    #nginx #tutorial
    Wed, Sep 3, 2014 11:58pm -07:00
    2 mentions

    Other Mentions

    • bear bear.im
      IndieWeb Note 1
      Sat, Apr 26, 2014 12:00am +00:00
    • russell.ballestrini.net
      Wed, Dec 21, 2016 1:54pm -07:00
Posted in /articles

Hi, I'm Aaron Parecki, Senior Security Architect at Okta, and co-founder of IndieWebCamp. I maintain oauth.net, write and consult about OAuth, and participate in the OAuth Working Group at the IETF. I also help people learn about video production and livestreaming and dabble in product design.

I've been tracking my location since 2008 and I wrote 100 songs in 100 days. I've spoken at conferences around the world about owning your data, OAuth, quantified self, and explained why R is a vowel. Read more.

  • Security Architect at Okta
  • IndieWebCamp Founder
  • OAuth WG Member

  • 🎥 YouTube Tutorials and Reviews
  • 🏠 We're building a triplex!
  • ⭐️ Life Stack
  • ⚙️ Home Automation
  • All
  • Articles
  • Bookmarks
  • Notes
  • Photos
  • Replies
  • Reviews
  • Trips
  • Videos
  • Contact
© 1999-2023 by Aaron Parecki. Powered by p3k. This site supports Webmention.
Except where otherwise noted, text content on this site is licensed under a Creative Commons Attribution 3.0 License.
IndieWebCamp Microformats Webmention W3C HTML5 Creative Commons
WeChat ID
aaronpk_tv