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 and how best to handle them.

Please log all API calls 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 so we can provide you with the most accurate answers.

Due to the vast amounts of 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:,   
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:,   
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:,   
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>  
<H1>Service Unavailable - Zero size object</H1>  
The server is temporarily unable to service your request.  Please try again  
Reference #15.9e5df6d8.1420397112.3b4627b8  


Allow enough time for connections to be made to Airship's servers

Setting a timeout limit of 60 seconds can result in higher success rates when accessing our API during extremely high loads. While our APIs normally respond immediately, sometimes our server infrastructure can become momentarily busy. Setting a 60 second timeout should tolerate any network and server load conditions and is our recommended best practice.

Retry on 503 and 500 error responses

A 503 or 500 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 502 or 504 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 a successful delivery. If there is any question about the result of a non-503 or 500 error return, please contact 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 

If you feel that Airship is experiencing a high rate of errors, please check our Status Page - EU 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 with 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 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 Airship SDK on our Developer Resources page.

Related Content

Was this article helpful?
1 out of 3 found this helpful
Submit a request