Status Codes and Messages

The first thing you should always do after calling an endpoint is check the HTTP status, followed by the code field in the JSON response. These status codes indicate whether or not the request succeeded or failed.

HTTP Status Code

The HTTP status code is always returned by the server. If an endpoint returns an HTTP status code other than 200 (OK), an authentication or other server error has occurred. In this case, there may or may not be a JSON message returned.

See also: HTTP Status Codes for a list of what codes can be raised, and what they mean.

JSON Status Code

Each endpoint also returns a field in the JSON response called code. The documentation for each endpoint states what codes are returned and their meaning. Generally, however, a value of 2xx (ie, between 200 and 299) means success and anything else means a failure of some kind.

Note: The HTTP status and the code field in the JSON response message share some of the same values. It is important not to confuse these two different status fields.

If an error does occur (and a JSON message is returned), the message field should contain a description of the failure. The code field should always be checked before attempting to read any other part of the JSON response, as other fields may be incomplete or missing if an error occurred.

Important: While the status code (ie, the code field in the response message) is considered part of the API contract, the message field is not. Developers must not rely on certain values being returned in the message field as they may change in the future. The message field should be used for diagnostic purposes only.

See also: Common Fields and Technical Resources for more information.