Making API responses match the request Content-Type

Wednesday, 1 February 2012

Hello Developers!

We’d like to change the content type of error responses to API requests. For anyone unfamiliar with the way things currently work, the current response body for 404, 500, and 503 errors is an HTML-formatted web page, which is a pain point for those of you expecting an XML or JSON response. We want to bring that more in line with the rest of the API, and will be making API error responses match the requested data format where possible.

Error responses for XML-based queries (including ATOM and RSS) will be served as Content-Type: application/xml; charset=utf-8 and look like these:

404 responses:

<?xml version="1.0" encoding="UTF-8"?>
<errors>
  <error code="34">Sorry, that page does not exist</error>
</errors>

503 responses:

<?xml version="1.0" encoding="UTF-8"?>
<errors>
  <error code="130">Over capacity</error>
</errors>

500 responses:

<?xml version="1.0" encoding="UTF-8"?>
<errors>
  <error code="131">Internal error</error>
</errors>

(Note that the 34, 130, and 131 codes are part of a larger effort to unify error messages across all of the API - while the text of the error message may change, the codes will stay the same.)

Responses for JSON-based requests will be served as Content-Type: application/json; charset=utf-8 and look like these:

403:

{"errors":[{"message":"Sorry, that page does not exist","code":34}]}

503:

{"errors":[{"message":"Over capacity","code":130}]}

500:

{"errors":[{"message":"Internal error","code":131}]}

JSONP users will also get the benefit of these error messages, as the callback parameter will be included in the error body. So if https://api.twitter.com/1/method.json?callback=foo responds with a 503 error, the response will be:

foo({"errors":[{"message":"Over capacity","code":130}]});

Hopefully you’re as excited about this as we are to be able to turn this behavior on. We’d like to make this change in one week, but if you have a reason why we should hold off, please let us know by posting in this discussion thread with your justification.

Cheers,
~Arne