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
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.
- Documentation Overview
- Intro into using SAPI
- Using Endpoints
- Common Fields
- Status Codes and Messages
- Validation Errors
- Spell Checker
- Search Query Tips
- Reporting Usage Events
- Filtering Unsafe Content
- Category Filtering
- Postcode Filtering
- Radius Filtering
- Address Search
- Suburb Filtering
- State Filtering
- Bounding Box Filtering
- Filtering by Content Type
- Filtering by Product Keyword
- Location Tier Filtering
- Filtering by Polygon
- Endpoint Reference