Push Notification Error Codes Guide

Push Notification or Google Cloud Messaging for Android (GCM), Apple Push Notifcation Service (APNS) or Windows Push Notifcation Service (WNS) are services that allows the Application owner to send data from the server to the application users’ device, and also to receive messages from devices on the same connection.


Below Section of the Document describes the Response/Error Codes received from the various Push Notification systems.

Application Push Notifications


Interpreting an error response

Here are the recommendations for handling the different types of error that might occur when trying to send a message to a device:

Missing Registration ID
Check that the request contains a registration ID (either in the registration_id parameter in a plain text message, or in the registration_ids field in JSON). Happens when error code is MissingRegistration.

Invalid Registration ID
Check the formatting of the registration ID that you pass to the server. Make sure it matches the registration ID the phone receives in the com.google.android.c2dm.intent.REGISTRATION intent and that you’re not truncating it or adding additional characters.
Happens when error code is InvalidRegistration.

Mismatched Sender
A registration ID is tied to a certain group of senders. When an application registers for GCM usage, it must specify which senders are allowed to send messages. Make sure you’re using one of those when trying to send messages to the device. If you switch to a different sender, the existing registration IDs won’t work. Happens when error code is MismatchSenderId.

Unregistered Device
An existing registration ID may cease to be valid in a number of scenarios, including:
If the application manually unregisters by issuing a com.google.android.c2dm.intent.UNREGISTERintent.
If the application is automatically unregistered, which can happen (but is not guaranteed) if the user uninstalls the application.
If the registration ID expires. Google might decide to refresh registration IDs.
If the application is updated but the new version does not have a broadcast receiver configured to receive com.google.android.c2dm.intent.RECEIVE intents.
For all these cases, you should remove this registration ID from the 3rd-party server and stop using it to send messages.
Happens when error code is NotRegistered.

Message Too Big
The total size of the payload data that is included in a message can’t exceed 4096 bytes. Note that this includes both the size of the keys as well as the values.
Happens when error code is MessageTooBig.

Invalid Data Key
The payload data contains a key (such as from or any value prefixed by google.) that is used internally by GCM in the com.google.android.c2dm.intent.RECEIVE Intent and cannot be used. Note that some words (such as collapse_key) are also used by GCM but are allowed in the payload, in which case the payload value will be overridden by the GCM value.
Happens when the error code is InvalidDataKey.

Invalid Time To Live
The value for the Time to Live field must be an integer representing a duration in seconds between 0 and 2,419,200 (4 weeks). Happens when error code is InvalidTtl.

Authentication Error
The sender account that you’re trying to use to send a message couldn’t be authenticated. Possible causes are:
Authorization header missing or with invalid syntax.
. Invalid project number sent as key.
. Key valid but with GCM service disabled.
. Request originated from a server not whitelisted in the Server Key IPs.

The server couldn’t process the request in time. You should retry the same request, but you MUST obey the following requirements:
. Honor the Retry-After header if it’s included in the response from the GCM server.
. Implement exponential back-off in your retry mechanism. This means an exponentially increasing delay after each failed retry (e.g. if you waited one second before the first retry, wait at least two second before the next one, then 4 seconds and so on). If you’re sending multiple messages, delay each one independently by an additional random amount to avoid issuing a new request for all messages at the same time.

Senders that cause problems risk being blacklisted.
Happens when the HTTP status code is between 501 and 599, or when the error field of a JSON object in the results array is Unavailable.

Internal Server Error
The server encountered an error while trying to process the request. You could retry the same request (obeying the requirements listed in the Timeout section), but if the error persists, please report the problem in the android-gcm group.
Happens when the HTTP status code is 500, or when the error field of a JSON object in the results array isInternalServerError.

Invalid Package Name
A message was addressed to a registration ID whose package name did not match the value passed in the request. Happens when error code is InvalidPackageName.



Response Codes

Status code Description
0 No errors encountered
1 Processing error
2 Missing device token
3 Missing topic
4 Missing payload
5 Invalid token size
6 Invalid topic size
7 Invalid payload size
8 Invalid token
10 Shutdown
255 None (unknown)



Response codes

Each HTTP message contains one of these response codes. WNS recommends that developers log the response code for use in debugging. When developers report an issue to WNS, they are required to provide response codes and header information.

HTTP response code Description Recommended action
200 OK The notification was accepted by WNS. None required.
400 Bad Request One or more headers were specified incorrectly or conflict with another header. Log the details of your request. Inspect your request and compare against this documentation.
401 Unauthorized The cloud service did not present a valid authentication ticket. The OAuth ticket may be invalid. Request a valid access token by authenticating your cloud service using the access token request.
403 Forbidden The cloud service is not authorized to send a notification to this URI even though they are authenticated. The access token provided in the request does not match the credentials of the app that requested the channel URI. Ensure that your package name in your app’s manifest matches the cloud service credentials given to your app in the Dashboard.
404 Not Found The channel URI is not valid or is not recognized by WNS. Log the details of your request. Do not send further notifications to this channel; notifications to this address will fail.
405 Method Not Allowed Invalid method (GET, CREATE); only POST (Windows or Windows Phone) or DELETE (Windows Phone only) is allowed. Log the details of your request. Switch to using HTTP POST.
406 Not Acceptable The cloud service exceeded its throttle limit. Log the details of your request. Reduce the rate at which you are sending notifications.
410 Gone The channel expired. Log the details of your request. Do not send further notifications to this channel. Have your app request a new channel URI.
413 Request Entity Too Large The notification payload exceeds the 5000 byte size limit. Log the details of your request. Inspect the payload to ensure it is within the size limitations.
500 Internal Server Error An internal failure caused notification delivery to fail. Log the details of your request. Report this issue through the developer forums.
503 Service Unavailable The server is currently unavailable. Log the details of your request. Report this issue through the developer forums.