Have a better error when offline for maintenance

I just noticed today my integration failed because the API was offline for maintenance. However, I only knew this because json parsing failed because the below was returned via the API. In my opinion, an API should never return HTML as consumers of the API are never setup to parse HTML, only the proper json. It should, instead, return some sort of json error when the API is offline for maintenance.


<!DOCTYPE html>
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <meta charset="utf-8">
    <title>Offline for Maintenance</title>
    <style media="screen">
      html,body,iframe {
        margin: 0;
        padding: 0;
      html,body {
        height: 100%;
        overflow: hidden;
      iframe {
        width: 100%;
        height: 100%;
        border: 0;
    <iframe src="https://d2jw9i16ku5n5z.cloudfront.net/ynab-api-production/static/ynab-getting-better.html"></iframe>
6replies Oldest first
  • Oldest first
  • Newest first
  • Active threads
  • Popular
  • I'll suggest HTTP code 418 as a potential response. 

  • Ha! Although teapot would be funny, I'd suggest a 503/ServiceUnavailable given the description of "The server is not ready to handle the request. Common causes are a server that is down for maintenance or that is overloaded."

  • We'd love to send a more semantically correct response when the API's in maintenance mode. Unfortunately, it's not that simple. Our host (Heroku) provides a mechanism to serve custom error pages, but those pages are `iframe`d and so not suitable as an API response (as you can see above). That said, we're still looking for a way around that limitation.

  • Thanks for the response. As a developer myself, I would humbly say it sounds like it's time for a new host. Any time a piece of the stack becomes a major limiting factor in doing what is proper, then it's time to change that piece of the stack.

    Like 1
  • It's probably very safe to say that there's a problem with the YNAB API anytime HTML is returned or, in my case, the payload doesn't deserialize properly. An unexpected problem is a problem, whether it's a 503, or a parsing exception. 

  • I set up a simple heroku application and put it in maintenance mode to test this. I can confirm that the HTTP response code is 503 Service Unavailable, and the content type is text/html (even when application/json is requested).

    The YNAB ruby gem client throws YNAB::ApiError with code set to 503 when this occurs.

Like Follow
  • 2 yrs agoLast active
  • 6Replies
  • 666Views
  • 3 Following