Android GCM 错误代码

GCM Error Codes

提问by Ian Lee

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.

我有一个发送 GCM 推送通知的服务器应用程序。每次发送 1000 个收件人都会返回一条消息，告诉我每个注册 ID 的状态。有些会有错误代码。是否有来自 Google 的文档告诉我我应该如何处理这些代码以及所有可能的错误代码是什么？我的 Google foo 没有出现任何问题。

回答by Eran

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

你看起来不够努力。所有的代码解释这里下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 IDCheck 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 IDCheck 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 SenderA 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 DeviceAn 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 BigThe 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 KeyThe 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 LiveThe 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 ErrorThe 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.

TimeoutThe 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 ErrorThe 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 NameA 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.

解释错误响应

以下是处理尝试向设备发送消息时可能发生的不同类型错误的建议：

缺少注册 ID检查请求是否包含注册 ID（在纯文本消息中的 registration_id 参数中，或在 JSON 中的 registration_ids 字段中）。当错误代码为MissingRegistration时发生。

无效的注册 ID检查您传递给服务器的注册 ID 的格式。确保它与手机在 com.google.android.c2dm.intent.REGISTRATION 意图中收到的注册 ID 相匹配，并且您没有截断它或添加其他字符。当错误代码为InvalidRegistration时发生。

不匹配的发件人注册 ID 与特定的发件人组相关联。当应用程序注册使用 GCM 时，它必须指定允许哪些发送者发送消息。尝试向设备发送消息时，请确保您正在使用其中之一。如果您切换到不同的发件人，现有的注册 ID 将不起作用。当错误代码为MismatchSenderId时发生。

未注册的设备现有的注册 ID 在许多情况下可能不再有效，包括：

• 如果应用程序通过发出 com.google.android.c2dm.intent.UNREGISTER 意图手动取消注册。
• 如果应用程序自动注销，如果用户卸载应用程序，这可能会发生（但不能保证）。
• 如果注册 ID 过期。Google 可能会决定刷新注册 ID。
• 如果应用程序已更新但新版本没有配置为接收 com.google.android.c2dm.intent.RECEIVE 意图的广播接收器。

对于所有这些情况，您应该从第 3 方服务器中删除此注册 ID，并停止使用它来发送消息。当错误代码为NotRegistered时发生。

消息太大 消息中包含的有效负载数据的总大小不能超过 4096 字节。请注意，这包括键的大小和值。当错误代码是MessageTooBig时发生。

Invalid Data Key有效载荷数据包含一个键（例如 from 或任何以 google 为前缀的值。），该键由 GCM 在 com.google.android.c2dm.intent.RECEIVE Intent 中内部使用，无法使用。请注意，GCM 也使用了一些词（例如collapse_key），但允许在有效载荷中使用，在这种情况下，有效载荷值将被 GCM 值覆盖。当错误代码为InvalidDataKey时发生。

无效的生存时间 生存时间字段的值必须是一个整数，表示 0 到 2,419,200（4 周）之间的持续时间（以秒为单位）。当错误代码为InvalidTtl时发生。

身份验证错误您尝试用于发送邮件的发件人帐户无法通过身份验证。可能的原因有：

• 授权标头丢失或语法无效。
• 作为密钥发送的项目编号无效。
• 密钥有效但禁用 GCM 服务。
• 请求源自未在服务器密钥 IP 中列入白名单的服务器。

检查您在 Authorization 标头中发送的令牌是否是与您的项目关联的正确 API 密钥。您可以通过运行以下命令来检查 API 密钥的有效性：

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\"]}"

如果您收到 401 HTTP 状态代码，则您的 API 密钥无效。否则你应该看到这样的东西：

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

如果要确认注册 ID 的有效性，可以通过将“ABC”替换为注册 ID 来实现。当 HTTP 状态代码为 401 时发生。

超时服务器无法及时处理请求。您应该重试相同的请求，但您必须遵守以下要求：

如果 GCM 服务器的响应中包含 Retry-After 标头，则应遵守该标头。在您的重试机制中实现指数退避。这意味着每次失败重试后延迟呈指数增长（例如，如果您在第一次重试前等待一秒钟，则在下一次重试前至少等待两秒钟，然后是 4 秒钟，依此类推）。如果您要发送多条消息，请将每条消息单独延迟一个额外的随机量，以避免同时对所有消息发出新请求。导致问题的发件人有被列入黑名单的风险。当 HTTP 状态代码介于 501 和 599 之间时，或者结果数组中 JSON 对象的错误字段为 Unavailable 时发生。

内部服务器错误服务器在尝试处理请求时遇到错误。您可以重试相同的请求（遵守超时部分中列出的要求），但如果错误仍然存​​在，请在 android-gcm 组中报告问题。当 HTTP 状态代码为 500 或结果数组中 JSON 对象的错误字段为InternalServerError 时发生。

无效的包名称消息发送到注册 ID，其包名称与请求中传递的值不匹配。当错误代码为InvalidPackageName时发生。

EDIT (06/06/2015) :

编辑（06/06/2015）：

A new error response codes table has been posted here.

新的错误响应代码表已在此处发布。

The new error responses :

新的错误响应：

Device Message Rate ExceededThe 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 ExceededThe 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.

Device Message Rate Exceeded发送到特定设备的消息速率太高。减少发送到此设备的消息数量，不要立即重试发送到此设备。

主题消息速率超出向特定主题的订阅者发送消息的速率太高。减少为此主题发送的消息数量，不要立即重试发送。

EDIT (07/21/2019) :

编辑（07/21/2019）：

A new error response codes table has been posted here.

新的错误响应代码表已在此处发布。