If you are an avid user of our server APIs to manage your push messaging, you're familiar with our HTTP server responses. Tracking this information is important to you in the event you need to contact us for any support issues.
Please Log your API requests and our responses
First, we recommend that you always log the HTTP response code that you get from each request. This will allow you to look back and find out if there was a problem with a particular request, or to trigger automatic retries.
Please see our documentation about the various HTTP Response Codes.
API logging examples:
A 202 or 200 API response code means that your API request was formatted correctly and accepted as a syntactically valid API call. A valid API request does not always mean that a resulting push would be sent. There are many possible reasons, the most common being:
- You may have sent a push to a tag or segment that's not associated with any devices.
- You may have pushed to a Channel ID or Named User that is not opted-in or installed.
We check these later in our processing of the push, not as part of our initial validation. The initial validation of the request (and the response you get) only pertains to whether your request was properly authenticated and formatted.
See our Android and iOS troubleshooting guides for more information on why your push may not have arrived as expected.
Successful API Request log example
Local Timestamp UTC: 2014-12-19 00:02:47
Request Method: <[POST]>,
Request URL: https://go.urbanairship.com/api/push/,
Request Body: {"device_types": "all", "notification": {"alert": "Tag\n2014-12-18 16:02:47"}, "audience": {"or": [{"tag": ["test_tag"]}]}},
Request Headers: {'Content-Length': '123', 'Accept-Encoding': 'gzip, deflate', 'Accept': 'application/vnd.urbanairship+json; version=3;', 'User-Agent': 'requests2311Machine', 'Connection': 'keep-alive', 'Content-Type': 'application/json', 'Authorization': 'Basic Q290eNFcXVMX2RkUGXBR'},
Response Code: 202,
Response Headers: {'transfer-encoding': 'chunked', 'data-attribute': 'push_ids', 'expires': 'Fri, 19 Dec 2014 00:02:47 GMT', 'server': 'Jetty(8.y.z-SNAPSHOT)', 'last-modified': 'Fri, 19 Dec 2014 00:02:47 GMT', 'connection': 'keep-alive, Transfer-Encoding', 'cache-control': 'max-age=0', 'date': 'Fri, 19 Dec 2014 00:02:47 GMT', 'content-type': 'application/vnd.urbanairship+json; version=3'},
Response Body Text: {"ok":true,"operation_id":"5d971120-8712-11e4-b80b-90e2ba2901f0","push_ids":["130f4882-4fad-4100-bb29-2008b15e3636"],"message_ids":[],"content_urls":[]}Unsuccessful API Request log example
Local Timestamp UTC: 2015-01-04 18:45:12
Request Method: <[POST]>,
Request URL: https://go.urbanairship.com/api/push/,
Request Body: {"device_types": ["ios", "android"], "audience": {"alias": ["71caaf8"]}, "notification": {"alert": "Check your email."}},
Request Headers: {'Authorization': 'Basic QXpUMkc3ljQ1NFcXVMXZXBR', 'Connection': 'keep-alive', 'User-Agent': 'requests2311Machine', 'Content-Type': 'application/json', 'Accept-Encoding': 'gzip, deflate', 'Accept': 'application/vnd.urbanairship+json; version=3;', 'Content-Length': '389'},
Response Code: 503,
Response Headers: {'Mime-Version': '1.0', 'Connection': 'close', 'Content-Type': 'text/html', 'Server': 'AkamaiGHost', 'Expires': 'Sun, 04 Jan 2015 18:45:12 GMT', 'Date': 'Sun, 04 Jan 2015 18:45:12 GMT', 'Content-Length': '274'},
Response Body Text: <HTML><HEAD>
<TITLE>Service Unavailable</TITLE>
</HEAD><BODY>
<H1>Service Unavailable - Zero size object</H1>
The server is temporarily unable to service your request. Please try again
later.
Reference #15.9e5df6d8.1420397112.3b4627b8
</BODY></HTML>
Retry on API errors
If you receive a 5xx response from our API, you should retry your request with an exponential backoff method. Errors happen on the internet from time to time, and our best practices recommend that if you first do not succeed, please try, try again. When retrying your API call, please insert a progressive delay, so your first retry may occur in 5 seconds, your second in 30, and progressive calls back off further until success. You may want to handle exceptions for persistent failures. Log files after persistent failures will be essential for us to diagnose the issue with you.
Authentication issues
If you received a 4xx response, there was some problem with your authentication or the structure of your request.
A 401 error from our API means that the authentication portion of your request was invalid.
Please make sure that you are not authenticating with the wrong set of App Key and Secret.
Push requests and many other API requests require your App Key and Master Secret for authentication, while others only require your App Key and App Secret.
In the API documentation for a given request, you should see something like this:
POST /api/push HTTP/1.1
Authorization: Basic <master authorization string>
Content-Type: application/json
Accept: application/vnd.urbanairship+json; version=3;
If the Authorization: includes <application authorization string> use your App Key and App Secret.
If the Authorization: includes <master authorization string> use your App Key and Master Secret.
If you get the error "(400) Bad Request. iOS payload, but nothing to deliver to (missing device_tokens, tags, segments, or aliases)", but you are still sending a valid API v3 payload, please make sure you are including both of the necessary headers in your API request, or else the API will think you are trying to match the formatting of the older API.
These headers are:
Content-type: application/json
Accept: application/vnd.urbanairship+json; version=3;
Examples of successful pushes
When we receive a successful push request, we return valuable information back to you about your request. A typical push response looks something like this:
{
"ok" : true,
"operation_id" : "df6a6b50-9843-0304-d5a5-743f246a4946",
"push_ids": [
"9d78a53b-b16a-c58f-b78d-181d5e242078",
]
}
And a rich message like this:
{
"ok" : true,
"operation_id" : "df6a6b50-9843-0304-d5a5-743f246a4946",
"push_ids": [
"9d78a53b-b16a-c58f-b78d-181d5e242078",
]
"message_ids":[
"lXiQ4roCcCDkmxlwDnER4x"
]
}
The key pieces that you want to keep are the push_ids for a standard push request and the message_ids for a rich push request. The 202 OK response means that we were successful in receiving your request for processing. The operation_id is currently saved for future functionality. Along with these responses, you should also track the full payload including the exact date and time of the request.
Why should you keep this information? We can use the push_ids and message_ids to look up your push in our systems.
API-initiated pushes are not listed in the Messages history in our web dashboard. Messages sent through the API are listed in the Activity Log with the exception of Unicast messages (messages sent to an individual Channel ID or Named User ID) and messages created using automation and sequences.
Saving these items can help us address problems you might have had with your push request. It also saves us valuable time when trying to determine other causes for problems with your push. If you're having trouble with a push notification and receiving something other than an OK from us, please refer to our HTTP troubleshooting guide.
You can find the general docs about push notifications sent via our API here.