Delen via

Push Notification Service response codes for Windows Phone 8

  • Artikel

[ 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

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.

Response Code

Notification Status

Device Connection Status

Subscription Status

Comments

200 OK

Received

Connected

Active

The notification request was accepted and queued for delivery. The server could respond with this status even though the device is currently transitioning into the Temp Disconnected state. This means the notification would not be delivered until the device returns from the Temp Disconnected state.

200 OK

Received

Temp Disconnected

Active

The notification request was accepted and queued for delivery. However, the device is temporarily disconnected. For more info, see Understanding the Temp Disconnected State.

200 OK

QueueFull

Connected

Active

The server maintains a maximum of 30 notifications (regardless of type) for each URI. Once the limit of 30 is reached, all new messages sent to the server are discarded until the device reconnects and the queue can be flushed.

200 OK

QueueFull

Temp Disconnected

Active

The server maintains a maximum of 30 notifications (regardless of type) for each URI. Once the limit of 30 is reached, all new messages sent to the server are discarded until the device reconnects and the queue can be flushed.

200 OK

Suppressed

Connected

Active

The push notification was received and dropped by the Push Notification Service. The Suppressed status can occur if the notification type was not enabled by calling BindToShellTile or BindToShellToast in the client application, if the raw notification was sent when the application was not in the foreground or if a Tile notification was sent with no Tile for the application pinned to start.

200 OK

Suppressed

Temp Disconnected

Active

The push notification was received and dropped by the Push Notification Service. The Suppressed status can occur if the notification type was not enabled by calling BindToShellTile or BindToShellToast in the client application, if the raw notification was sent when the application was not in the foreground or if a Tile notification was sent with no Tile for the application pinned to start.

400 BadRequest

N/A

N/A

N/A

This error occurs when the cloud service sends a notification request with a bad XML document or malformed notification URI.

401 Unauthorized

N/A

N/A

N/A

Sending this notification is unauthorized. This error can occur for one of the following reasons:

  • There is a mismatch between the subject name of the certificate on the cloud service and the subject name of the certificate on the Push Notification Service.

  • If the token has been modified.

  • If the token is not valid for its subscription.

404 Not Found

Dropped

Connected

Expired

The subscription is invalid and is not present on the Push Notification Service. The cloud service should stop sending new notifications to this subscription, and drop the subscription state for its corresponding application session.

404 Not Found

Dropped

Temp Disconnected

Expired

The subscription is invalid and is not present on the Push Notification Service. The cloud service should stop sending new notifications to this subscription, and drop the subscription state for its client.

404 Not Found

Dropped

Disconnected

Expired

The subscription is invalid and is not present on the Push Notification Service. The cloud service should stop sending new notifications to this subscription, and drop the subscription state for its client.

405 Method Not Allowed

N/A

N/A

N/A

Invalid method (PUT, DELETE, CREATE). Only POST is allowed when sending a notification request.

406 Not Acceptable

Dropped

Connected

Active

This error occurs when an unauthenticated cloud service has reached the per-day throttling limit for a subscription, or when a cloud service (authenticated or unauthenticated) has sent too many notifications per second. The cloud service can try to re-send the push notification every hour after receiving this error. The cloud service may need to wait up to 24 hours before normal notification flow will resume.

406 Not Acceptable

Dropped

Temp Disconnected

Active

This error occurs when an unauthenticated cloud service has reached the per-day throttling limit for a subscription, or when a cloud service (authenticated or unauthenticated) has sent too many notifications per second. The cloud service can try to resend the push notification every hour after receiving this error. The cloud service may need to wait up to 24 hours before normal notification flow will resume.

412 Precondition Failed

Dropped

Disconnected

N/A

The device is in a disconnected state. The cloud service should continue sending notifications as usual even though those notifications are dropped because when the device returns to Connected status this ensures the notification flow continues to the device.

503 Service Unavailable

N/A

N/A

N/A

The Push Notification Service is unable to process the request. The cloud service should resend the notification later.

Custom headers

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

Header

Description/Specification

MessageID

The notification message ID associated with the response. If the POST request delivered to the Push Notification Service did not contain the MessageID custom header, MessageID will not be returned in the response. For more info, see Sending push notifications for Windows Phone 8.

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

NotificationStatus

The status of the notification received by the Microsoft Push Notification Service.

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

DeviceConnectionStatus

The connection status of the device.

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

SubscriptionStatus

The subscription status.

"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