Push Notification Service response codes for Windows Phone 8

[ This article is for Windows Phone 8 developers. If you’re developing for Windows 10, see the latest documentation. ]

After your cloud service sends a push notification to the Microsoft Push Notification Service, your cloud service will receive one of many response codes with possible custom headers.

Important Note:
The Microsoft Push Notification Service in Windows Phone is an asynchronous, best-effort service that offers third-party developers a channel to send data to a Windows Phone app from a cloud service in a power-efficient manner.

This topic contains the following sections.

• Message response format
• Push Notification Service response codes
• Custom headers
• Transition flow for Device Connection Status
• Understanding the Temp Disconnected State
• Related Topics

Message response format

Responses from the Microsoft Push Notification Service will be in the following format:

HTTP/1.1 [error code] [error text] 
Date: [HTTP-date]
[Custom HTTP Headers]

• [error code]
  A three-digit error code. See a list of error codes below.

• [error text]
  The explanation of the error.

• [Custom HTTP Headers]
  The custom HTTP headers are defined below.

Push Notification Service response codes

The following table describes both error and non-error response codes that may be returned to your cloud service. Response codes are not indications the message has been received by the device. They only indicate that the server has received the notification and queued it for delivery at the next possible opportunity for the device.

Custom headers

Each response that is sent from the Push Notification Service may include one or more of the following custom headers:

"X-MessageID"":"1*MessageIDValue
MessageIDValue = STRING (uuid)
//For example:
X-MessageID:<UUID>

"X-NotificationStatus"":"1*NotificationStatusValue
NotificationStatusValue = STRING (Received|Dropped|QueueFull|)
//For example:
X-NotificationStatus:Received

"X-DeviceConnectionStatus"":"1*DeviceConnectionStatusValue
DeviceConnectionStatusValue = STRING
(Connected|InActive|Disconnected|TempDisconnected)
//For example:
X-DeviceConnectionStatus:Connected

"X-SubscriptionStatus"":"1*SubscriptionStatusValue
SubscriptionStatusValue = STRING
(Active|Expired)
//For example:
X-SubscriptionStatus:Active

Transition flow for Device Connection Status

The following flow represents the cycle a device goes through between the Connected, Temp Disconnected and Disconnected states.

• In the Connected state the device has an active connection to the push notification server and can receive notifications in real time.

  • This is the expected state for 70-80% of devices at any given time.

• In the Temp Disconnected state the device has transitioned to a temporary state where it has lost connectivity with the push notification server and will actively try and reconnect as soon as a valid internet connection is available on the device.

  • A device can remain in this state for up to 24 hours.

  • During this period all notifications sent to the device that aren’t over the QueueFull limit of 30 are stored on the server for later delivery.

  • Common reasons for a device to enter this state are listed in the guidance for Temp Disconnected below.

  • On average up to 30% of devices may return this status at any given time.

• In the Disconnected state the device has been disconnected from the push notification server for more than 24 hours, but will still actively try to reconnect to the push notification server when a valid internet connection is available on the device.

  • Once a device enters the disconnected state, all queued messages for that device and any new messages sent to that device are discarded and are not delivered when the device reconnects to the push notification server.

  • Disconnected mobile devices are typically in this state due to owner intent, meaning the user has intentionally disabled their data connection or physically powered off the device.

  • On average 10-15% of devices may return this status at any given time.

Understanding the Temp Disconnected State

This response code can occur for a variety of reasons, including but not limited to:

• To reduce network load and latency, mobile operator network configurations can vary greatly in the amount of time a persistent data connection is allowed to live. The Push Notification Client attempts to mitigate these persistent data connection limitations, but there is a lower bound after which it is power-inefficient to mitigate this situation. This may lead to devices experiencing the OK/Received/Temporarily Disconnected/Active state as a result of the data connection being interrupted.

• The device is outside the coverage area of their carrier and the user has chosen to disable data connection when roaming.

• The device has a Pay-As-You-Go plan and has temporarily disabled the data connection or has a restrictive data plan option.

• The device is on the edge of a coverage area and the data connection is not reliable.

• If Wi-Fi is being used and cellular data is not available, the device must have a clear path to the internet for push notifications to be received. This can be problematic on some corporate networks.

• The user has Data Sense enabled and has gone over their data plan limit so push notifications are disabled until they get back on track with their data plan. In this case, Temp Disconnected may transition to Disconnected for this user and not recover until they are back on track.

• The user has Battery Saver enabled and the Battery Saver indicator (the heart on the battery icon in the system tray) is showing. During this state, the push connection is turned off to conserve battery. During prolonged periods of the Battery Saver mode being active, the device could eventually transition to the Disconnected state.

• The device is alternating between cell and Wi-Fi connections and the connection is not in a steady state.

See Also

Other Resources

Sending push notifications for Windows Phone 8

Push notifications for Windows Phone 8