External API Responses Status/Error Codes

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 

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
}

Handling Error Responses

General guideline for handling responses/errors below:

IF  (Response 40X )  

 Issue on Client side log error so alert goes to IT team

IF  (Response 50X )  

 RETRY until limit hit

IF  (Retry limit hit )

Network connectivity issue or issue on xtremepush side, log error so alert goes to IT team who can escalate with xtremepush if needed

IF (Response 200)

 Success

Regarding API retries, our API team recommends the following as best practice:
If a 5XX response code is returned from an API request, then the request can be retried
One strategy for this (depending on your use case) is to send one retry immediately and then, if that still returns the same code, try once more after 30 seconds. The request, response and timestamp for anything other than a 2XX response code should be recorded so it can be looked into later