The Buzz API responds to every request with an http status indicating whether the request was successful, along with a json response. The json response includes:
| JSON element | Description | Always Present |
|---|---|---|
success | Boolean with true=success, false=failure | Yes |
payload | json results of the request. For a GET request will include the results. For a POST or PUT will include the unique id of the object. | No |
message | Plain-text description of the result | No |
error | json element with any error messages or warnings | No |
id | ID of newly created object on POST | No |
The first element of any API response will be the "Success" element, which will either be true or false. Example:"success": true
When a GET request successfully executes, the second element in the response will be the payload, which will contain the data requested. Example of a successful GET ot the right:
{ "success": true, "payload": { "user_id": 1, "first_name":"Danny" ... }}When a POST successfully executes, the payload element will be a success message, and an id element will be returned indicating the unique id of the object that was created. Example of a successful POST to the right:
{ "success": true, "payload": "user updated with ID 4", "id": 4}Successful PUT/DELETE Responses
Successful PUT/DELETE Responses
When a DELETE or PUT request successfully executes, the "payload" element will be a list of messages and useful data for each affected object. Example of a successful POST to the right:
{ "success": true, "payload": [ { "id": 1, "success": false, "error_code": "AD_BAD_VALIDATION", "message": [ "ERROR: Error creating campaign_budget, field improperly formatted decimal" ] }, { "id": 30, "success": true, "message": "campaign updated successfully" } ], "errors": [ "ERROR: campaign update: 1 updated successfully, 1 with errors" ]}Unsuccessful responses will aggregate all errors in the "errors" element, as shown in the example to the right:
{ "success": false, "payload": "Nothing found or problem with the query", "errors": { "ERROR: Nothing found matching those criteria", "WARNING: Something not so bad happened" }}Note, if the only error condition resulting from a request was a WARNING, the request will have success=true, but will also have a non-empty errors element.
HTTP Codes
HTTP Codes
Buzz uses HTTP status codes to indicate whether a request was successful. If the response's HTTP code is 200, all worked well. The following codes represent other outcomes:
| HTTP Code | Meaning |
|---|---|
| 200 | OK |
| 400 | Bad Request, method not supported by Buzz. |
| 401 | Unauthorized, user doesn't have rights. See Accounts, Users, Roles, Permissions. |
| 405 | Method not allowed by API. For example, some elements are read-only and cannot accept POST requests. |
| 406 | Not acceptable, missing parameters or bad parameters. This is the most common error code when field validation fails for any reason. |
| 409 | Conflict, thrown when an API request throws a WARNING and the request was made in strict mode. When not in "strict" mode a WARNING will return a 200. See: Using Extras for Fine-Tuning API Usage for more on strict mode. |
| 429 | Rate limiting, thrown when an excessive number of requests are made in a short amount of time. Rate limiting is currently applied to the Report Queue and Authentication endpoints. |
| 500 | Internal server error, generally problem with the database or system setup. |
Updated over 4 years ago
