Response and error handling

The response format for all API calls is unified, and - silently brushing over potential bugs - all behave the same way.

The response contains a status field, which can either be “OK” or “Error”. Successful calls will have the response field populated, and the error field set to null. For errors, it’s the other way around. Makes sense?

The status codes for successful operations are the HTTP status codes in the 2xx range , errors are in the 5xx range. We got - at least - that one right.

The format for a successful call looks like this:

{
  "status": "OK",
  "response": ...,
  "error": null
}

All API calls also support the JSONP format, by adding the callback parameter to the URL. The response looks like this (assuming ‘cb’ as the callback value, and formatted for readability):

/**/
typeof cb === 'function' && cb({
   "status":"OK",
   "response": ...,
   "error":null
});

If an error should occur in the backend, then the response will look like this:

{
  "status": "Error",
  "response": null,
  "error": {
    "name": "...",
    "message": "..."
  }
}

API access errors, like insufficient permissions, are formatted differently, and look like this:

{
  "statusCode": ...,
  "message": "..."
}

The statusCode field matches the HTTP response status code.

Should be fairly self-explanatory.