Twitter Developers: Watch For Changing Response Codes

All Twitter APIs will soon use HTTP error code 400 for calls beyond your rate limit. One of Twitter's most popular services, the Search API, currently uses error code 503. You'll want to update any of your applications that use Twitter search so that they're looking for the right code.

Twitter Platform engineer Wilhelm Bierbaum announced the change:

In an effort to simplify our APIs, we are standardizing the response
codes returned by our various systems. Historically, the Search API
has returned 503 for Rate Limiting whereas the REST API has returned
400. So, we are changing the response codes sent back from the Search

Starting Wednesday, December 16th, 2009 the search API will respond
with error code 400 in the event that the number of requests you have
made exceeds the quota afforded by your rate limit.

Twitter is growing fast and the platform team is building new interfaces just as quickly. It's good to see that Twitter is taking the time to ensure consistency in its API.

As for the error codes, here is how the W3C describes them:

  • 400 Bad Request - The request could not be understood by the server due to malformed syntax. The client SHOULD NOT repeat the request without modifications.
  • 503 Service Unavailable - The server is currently unable to handle the request due to a temporary overloading or maintenance of the server.

From the descriptions above, neither seem like a perfect fit. However, one big difference is that 4xx status codes are client errors, while 5xx are server errors. In that sense, 400 seems like a good choice.

If you have an API yourself, there's a good discussion at Stack Overflow about choosing meaningful error codes.

Be sure to read the next Best Practices article: Google APIs Get Faster Thanks to Smart Optimizations