Error handling

Our API is RESTful. That means that the first indication you'll have that something has gone wrong will be an HTTP status code. Generally speaking, here's the list of status codes our API will return:

Code	Meaning in API
200 OK	Successful request. Response in body.
204 No Content	Request was successful, but no matches were found.
404 Not Found	You're trying to access an API resource that doesn't exist.
417 Expectation Failed	You submitted a query that doesn't adhere to data format restrictions.
500 Internal Server Error	Something is seriously borked.

In the event that you get an answer containing a 417 or a 500, we'll usually try to send you a JSON response that indicates what the heck went wrong. In the event of a 417, you'll get a JSON array with the list of errors that occurred when trying to process your query. (That's right, all at once. Go ahead, swoon.) That will look something like this:

[
  {
    "fieldId": "sessionId",
    "error": "invalidId",
    "message": "The sessionId provided was invalid."
  },
  {
    "fieldId": "before",
    "error": "invalidDate",
    "message": "The before provided was an invalid date."
  },
  ...
]

In the event that the API service completely falls over and returns a 500, we can't make any promises about what will happen. If it was something that doesn't hit our error handler, all bets are off, you're probably getting an HTML page. If it was something that our error handler caught, then hopefully you'll get a JSON response body like this:

{
  "id": "An ID you should use when filing a bug",
  "error": "An error message hopefully telling you something meaningful."
}

If you see one of those, please file a bug report and let us know. Include the error ID, as that will (hopefully) be linked to a stack trace.