Best practices for 500 and 503 API errors

This best practices guide is designed to help understand how to best handle occasional errors that can be encountered while using our APIs. While we make significant attempts to accept and process all API requests to our service, some errors will be encountered from time to time. This guide will attempt to explain the nature of various errors how best to handle them.

Please log all API call and responses

Please log your full API requests and our API responses to you. If you encounter an error while using our API, we'll ask you for your API log data in order to see your API request and our API response to you as part of our fact finding mission and so we can provide you with the most accurate answers.

Due to the vast amounts API traffic sent to our service, we are required to rotate our log data relatively frequently and usually only have the past few hours of log data to analyze. If you have a question about events prior to our log retention history, we would need to work with you to examine your log data on what you experienced with our service.

API logging examples

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"]}]}},   
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 503 error responses

A 503 error means that we did not accept your request for processing. Please retry with an exponential backoff. If your first API call does not succeed, please retry your API request as a second retry will typically succeed. For more information on exponential backoff, please see Exponential backoff - Wikipedia, the free encyclopedia

Other 5xx errors, such as 500 errors must be treated differently. Requests that result in these errors may result in notifications and other messages being delivered to devices as expected. 

Prior to retrying, please check any test devices that should have received the message to see if there was successful delivery. If there is any question about the result of a non-503 error return, please contact Urban Airship Support providing the logs in the examples above.

 

Some errors are expected

While we strive for 100% service uptime all the time, our service does experience occasional errors. Furthermore, occasional errors will occur outside of our network, on the Internet itself. Because of this we recommend retrying requests as is sane given your use case and the information above.

Check our Status Page 

Urban Airship guarantees 99.5% uptime service reliability. If your error rate is less than .5%, a retry is your best path forward. If you feel that Urban Airship is experiencing a higher than .5% failure rate, please check our Status Page to verify if we have a known service issue that we're actively working on. If there is a current service issue, you may want to hold off on subsequent API activity until we have resolved the issue. 

Common sources of errors

  • Expect: 100-Continue: We've always attempted to support this usage, but based on recent analysis our customers that use Expect: 100-Continue are receiving a lower quality of service from us. This, combined the fact that our API's usage patterns do not benefit from Expect: 100-Continue (i.e. small POST bodies) has motivated us to disable support for it service-wide. See Expect: 100-Continue Issues and Risks for more information
  • Service API traffic. Our SDK connects your app to https://combine.urbanairship.com/warp9. If you are experiencing client side network failures, please don't worry; our SDK will automatically retry upon network failures. Using our unmodified client library SDK is required to troubleshoot any client-side non-network issues. You can find the latest versions of the Urban Airship SDK on our Developer Resources page.

Related Content