GCM Error Codes

Question

I've got a server app that sends GCM push notifications. Each send of 1000 recipients returns a message that tells me the status of each registration ID. Some will have error codes. Is there a document somewhere from Google that tells me how I'm expected to handle these codes and what all the possible error codes are? My Google foo isn't turning up anything.

Solution

You didn't look hard enough. All the codes are explained here under Interpreting an error response.

I tried to copy and paste it in order for it not to be a link only answer, but the formatting is a bit off:

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.UNREGISTER intent.
• 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.

Check that the token you're sending inside the Authorization header is the correct API key associated with your project. You can check the validity of your API key by running the following command:

api_key=YOUR_API_KEY

curl --header "Authorization: key=$api_key" --header Content-Type:"application/json" https://android.googleapis.com/gcm/send -d "{\"registration_ids\":[\"ABC\"]}"

If you receive a 401 HTTP status code, your API key is not valid. Otherwise you should see something like this:

{"multicast_id":6782339717028231855,"success":0,"failure":1,"canonical_ids":0,"results":[{"error":"InvalidRegistration"}]}

If you want to confirm the validity of a registration ID, you can do so by replacing "ABC" with the registration ID. Happens when the HTTP status code is 401.

Timeout 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 is InternalServerError.

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.

EDIT (06/06/2015) :

A new error response codes table has been posted here.

The new error responses :

Device Message Rate Exceeded The rate of messages to a particular device is too high. Reduce the number of messages sent to this device and do not immediately retry sending to this device.

Topics Message Rate Exceeded The rate of messages to subscribers to a particular topic is too high. Reduce the number of messages sent for this topic, and do not immediately retry sending.

EDIT (07/21/2019) :

A new error response codes table has been posted here.

Comments

[Ian Lee]

Thanks, Eran! I'm ashamed to say that I looked right over that part of the page several times. I think the format of it threw me off.

[Admin]

@Eran Link in the answer doesn't have the content anymore: developer.android.com/google/gcm/http.html#error_codes Last week i was able to see those contents. I am not sure what happened over the weekend.

[Eran]

@TamilVendhanKanagaraju Well, in that case, it's a good thing the content is here.

[Admin]

@Eran: Yeah, that's true. Thanks for capturing it here. :-)

[Eran]

@TamilVendhanKanagaraju Now there's a new link containing the error codes. I added it to the answer.