After making a https POST request to external-api.xtremepush.com using an API method any response is returned as a JSON formatted object. These JSON objects take the following form.
{
"code" : integer http error/success code
"success" : boolean - whether client request is successful
"message" : string system error message if code is error (4xx-5xx).
"errors" : errors list if success is false (optional)
"data" : contains array of response data (optional)
"model" : contains created / updated object attributes (optional)
}
The xtremepush API attempts to return appropriate HTTP status codes for every request, list below.
Response Codes
| Code | Text | Description |
| 200 | OK | Success. Everything worked as expected. |
| 400 | Bad Request | Client error indicating the request was invalid or cannot be otherwise served. An accompanying error message will explain further. Requests without authentication are considered invalid and will yield this response. |
| 401 | Unauthorized | Client error indicating that Authentication failed. |
| 403 | Forbidden |
Client error indicating that the request is understood, but it has been refused or access is not allowed. API Access may not be authorised for your account. Contact your account manager. |
| 404 | Not Found | Client error indicating that the URI requested is invalid or the resource requested, does not exists. Can also be returned when the requested format is not supported by the requested method. |
| 405 | Method Not Allowed | The method specified in the Request-Line is not allowed for the resource identified by the Request-URI. Often caused by a simple client error where API method has a typo in url used. |
| 410 | Gone | This resource is gone. Used to indicate that an API endpoint has been turned off. |
| 429 | Too Many Requests | Server response returned when a request cannot be served due to the application’s rate limit having been exhausted for the resource. |
| 500 | Internal Server Error | Server error indicating something is broken. Please post a support ticket with additional details of your request, so the xtremepush team can investigate. |
| 502 | Bad Gateway | Server error that could indicate xtremepush API may be down or being upgraded. This could also indicate an issue at the web server layer. Please post a support ticket with additional details of your request, so the xtremepush team can investigate. |
| 503 | Service Unavailable | The xtremepush API servers are up, but overloaded with requests. Try again later. |
| 504 | Gateway timeout | The xtremepush servers are up, but the request couldn’t be serviced due to some failure en route. Try again later. |
Sample Success Responses
A succesfull response will contain:
"code": 200
"success": true
"data"/"model": body of response (optional) present if an object or list of objects is to be returned
The message field may be ignored and the body of the response will be found in the data/model field where appropriate. For example if using a create or update method on an object such as a campaign, segment or location then the attributes of that object will be returned in the model field as shown in the example below. If an info method is used to return the attributes of a specific method then the model field will also be used.
{
"code": 200,
"message": "Location is successfully updated",
"model": {
"address": "48 Wall St, New York, NY 10005, USA",
"country": "US",
"groups_str": "liquid space",
"id": 4584,
"latitude": "40.7065668",
"longitude": "-74.00904220000001",
"project_id": 785,
"radius": 100,
"title": "48 Wall St, New York, NY 10005, USA",
"type": 0
},
"success": true
}
If a list method is used to return a list of objects such as campaigns, segments, locations, devices etc. then the data field is used to return the list of objects in an array.
{
"code": 200,
"data": [
{
"address": "Port Jackson NSW 2000, Australia",
"country": "AU",
"groups_str": "Theatre",
"id": 2858,
"latitude": "-33.85569128426597",
"longitude": "151.20608897777106",
"project_id": 785,
"radius": 100,
"title": "Sydney",
"type": 0
},
{
"address": "Waterloo Ln, Dublin Southside, Dublin 4, Ireland",
"country": "IE",
"groups_str": "mikeTest,newGeo",
"id": 3328,
"latitude": "53.3297221",
"longitude": "-6.2461803999999574",
"project_id": 785,
"radius": 200,
"title": "waterloo ln, Dublin",
"type": 0
},
{
"address": "8-9 Sussex Terrace, Dublin 4, Ireland",
"country": "IE",
"groups_str": "Test",
"ibeacon_major": "101",
"ibeacon_minor": "101",
"ibeacon_uuid": "F7826DA6-4FA2-4E98-8024-BC5B71E08933",
"id": 4236,
"latitude": "53.33133578333072",
"longitude": "-6.251659181788227",
"project_id": 785,
"radius": 5,
"title": "Showcase (BC5B71E08933)",
"type": 2
},
{
"address": "48 Wall St, New York, NY 10005, USA",
"country": "US",
"groups_str": "liquid space",
"id": 4584,
"latitude": "40.7065668",
"longitude": "-74.00904220000001",
"project_id": 785,
"radius": 100,
"title": "48 Wall St, New York, NY 10005, USA",
"type": 0
}
],
"success": true
}
Sample Error Responses
When working with the API you should handle all the standard http 4xx-5xx error codes that may be a possible response. The 4xx errors will indicate an issue on the client side such using an invalid url or having incorrect API params. These are most likely to encountered when you are initially setting up your API integration or when breaking updates are made on the client side. Where possible additional information will be provided to help you debug on the client side. For example when there is an issue with your request a typical 400 response will contain:
"code": 400 "success": false
"message":human readable system error message
"errors": list of parameter specific errors giving further information (optional)
The message field will contain a human readable message. For example where there is an issue related to authentication via your app token you may see:
{
"code": 400,
"message": "apptoken is invalid.",
"success": false
}
Or
{
"code": 400,
"message": "apptoken cannot be blank.",
"success": false
}
When working with update, execute or info methods for objects such as campaigns, segments, locations, devices etc. if you are missing or have some issue with the id of the object you want to access you may see:
That you have omitted the id
{
"code": 400,
"message": "id cannot be blank.",
"success": false
}
Or that there is no object with that id
{
"code": 404,
"message": "Not Found",
"success": false
}
When working with methods like create where you often have to provide more params then you can receive more detailed error information related to params. For example if you attempted to create an iBeacon location and you omitted the required ibeacon_major field and you entered an incorrect int type for the required ibeacon_uuid field then you would receive a response with the detailed param errors list in the errors field.
{
"code": 400,
"errors": {
"ibeacon_major": [
"iBeacon Major cannot be blank."
],
"ibeacon_uuid": [
"iBeacon UUID must be a string."
]
},
"message": "Location is not created",
"success": false
}
0 Comments