FCM 错误代码

HTTP v1 API 的 REST 错误代码

HTTP v1 API 的 HTTP 错误响应包含错误代码、错误消息和错误状态。它们可能还包含一个 details 数组，其中带有有关错误的更多详细信息。

以下是两个错误响应示例：

示例 1：数据消息中包含无效值的 HTTP v1 API 请求的错误响应

{
  "error": {
    "code": 400,
    "message": "Invalid value at 'message.data[0].value' (TYPE_STRING), 12",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.BadRequest",
        "fieldViolations": [
          {
            "field": "message.data[0].value",
            "description": "Invalid value at 'message.data[0].value' (TYPE_STRING), 12"
          }
        ]
      }
    ]
  }
}

示例 2：注册令牌无效的 HTTP v1 API 请求的错误响应

{
  "error": {
    "code": 400,
    "message": "The registration token is not a valid FCM registration token",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.firebase.fcm.v1.FcmError",
        "errorCode": "INVALID_ARGUMENT"
      }
    ]
   }
}

请注意，这两条消息的代码和状态相同，但详细信息数组包含不同类型的值。第一个示例的类型为 type.googleapis.com/google.rpc.BadRequest，表示请求值存在错误。第二个示例的类型为 type.googleapis.com/google.firebase.fcm.v1.FcmError，存在 FCM 特定错误。对于许多错误，详细信息数组包含您调试和找到解决方案所需的信息。

下表列出了 FCM v1 REST API 错误代码及其说明。

错误代码	说明和解决步骤
`UNSPECIFIED_ERROR` 无法提供有关此错误的更多信息。	无。
`INVALID_ARGUMENT`（HTTP 错误代码 = 400）请求参数无效。系统会返回类型为 `google.rpc.BadRequest` 的扩展程序，以指定哪个字段无效。	可能的原因包括注册无效、软件包名称无效、消息过大、数据键无效、TTL 无效或其他参数无效。注册无效：请检查您传递到服务器的注册令牌的格式。请确保它与客户端应用在注册 FCM 时获得的注册令牌相符。请勿截断令牌或添加其他字符。软件包名称无效：请确保消息发送至软件包名称与请求中传递的值相匹配的注册令牌。消息过大：请确保消息中包含的载荷数据的总大小不超过 FCM 限制：大多数消息的上限是 4096 字节；如果是主题消息，则上限为 2048 字节。这包括键和值。数据键无效：请确保载荷数据不包含由 FCM 内部使用的键（例如 from、gcm 或任何以 google 为前缀的值）。请注意，FCM 使用的某些字词（例如 collapse_key）也允许在载荷中使用，在这种情况下，FCM 值会覆盖载荷值。 TTL 无效：请确保 ttl 中使用的值是表示时长（以秒为单位）的整数值，且介于 0 到 2,419,200（即 4 周）之间。参数无效：请确保提供的参数具有正确的名称和类型。
`UNREGISTERED`（HTTP 错误代码 = 404）应用实例已从 FCM 取消注册。这通常意味着所使用的令牌不再有效，必须使用新令牌。	此错误可能是由于缺少注册令牌或令牌未注册所导致。缺少注册：如果消息的目标是 `token` 值，请检查请求是否包含注册令牌。未注册：现有注册令牌在很多情况下都可能会失效，包括： - 客户端应用取消 FCM 注册。 - 客户端应用自动取消注册（用户卸载应用时可能发生此情况）。例如，在 iOS 中，APNs 反馈服务报告称 APNs 令牌无效。 - 注册令牌过期（例如 Google 可能决定更新注册令牌，或者 iOS 设备的 APNs 令牌已过期）。 - 客户端应用已更新，但新版本未配置为接收消息。对于所有这些情况，请从应用服务器中移除此注册令牌，并停止用其发送消息。
`SENDER_ID_MISMATCH`（HTTP 错误代码 = 403）进行身份验证的发送者 ID 与注册令牌的发送者 ID 不同。	一个注册令牌与一组特定的发送者关联。当客户端应用注册 FCM 时，必须指定允许哪些发送者发送消息。在向客户端应用发送消息时，您应当使用这些发送者 ID 之一。如果您改用其他发送者，则现有的注册令牌将不起作用。
`QUOTA_EXCEEDED`（HTTP 错误代码 = 429）超出消息目标的发送上限。系统会返回类型为 `google.rpc.QuotaFailure` 的扩展程序，以指定超出的配额。	超出消息投递率配额、超出设备消息投递率配额或超出主题消息投递率配额可能会导致此错误。超出消息投递率：消息发送速率过高。您必须降低发送消息的总速率。使用指数退避算法（初始延迟时间至少为 1 分钟）重试被拒绝的消息。超出设备消息投递率：向特定设备发送消息的速率过高。请参阅向单一设备发送消息的最大速率。请减少发送到此设备的消息数量，并使用指数退避算法重试发送。超出主题消息投递率：向特定主题的订阅者发送消息的速率过高。请减少针对此主题发送的消息数量，并使用指数退避算法（最小初始延迟时间为 1 分钟）重试发送。
`UNAVAILABLE`（HTTP 错误代码 = 503）服务器过载。	服务器无法及时处理请求。重试同一请求，但您必须： - 如果 FCM 连接服务器发出的响应中包含 Retry-After 标头，则应在该标头指明的间隔后重试。 - 在您的重试机制中实现指数退避。（例如，如果等待一秒钟后进行第一次重试，则至少要等待两秒钟再进行下一次重试，然后等待四秒钟，依此类推）。如果您要发送多条消息，请考虑应用抖动。如需了解详情，请参阅处理重试，或查看 FCM 状态信息中心，确定是否存在影响 FCM 的持续性服务中断。导致出现问题的发送者有可能会被列入拒绝名单。
`INTERNAL`（HTTP 错误代码 = 500）发生了未知内部错误。	服务器在尝试处理请求时遇到错误。您可以按照处理重试中的建议重试同一请求，或查看 FCM 状态信息中心，确定是否存在影响 FCM 的持续性服务中断。如果错误仍然存在，请与 Firebase 支持团队联系。
`THIRD_PARTY_AUTH_ERROR`（HTTP 错误代码 = 401）APNs 证书或 Web 推送身份验证密钥无效或缺失。	无法发送以 iOS 设备或 Web 推送注册为目标的消息。请检查您的开发和生产环境凭据是否有效。

Admin SDK 错误代码

下表列出了 Firebase Admin FCM API 错误代码及其说明，包括建议的解决步骤。

错误代码	说明和解决步骤
`messaging/invalid-argument`	向 FCM 方法提供的参数无效。错误消息中应包含更多信息。
`messaging/invalid-recipient`	预期的消息接收者无效。错误消息中应包含更多信息。
`messaging/invalid-payload`	提供的消息载荷对象无效。错误消息中应包含更多信息。
`messaging/invalid-data-payload-key`	数据消息载荷包含无效键。如需了解受限制的键，请参阅 `DataMessagePayload` 的参考文档。
`messaging/payload-size-limit-exceeded`	提供的消息载荷超出了 FCM 大小限制。对于大多数消息，此限制为 4096 字节。对于发送到主题的消息，此限制为 2048 字节。键和值都会计入载荷总大小。
`messaging/invalid-options`	提供的消息选项对象无效。错误消息中应包含更多信息。
`messaging/invalid-registration-token`	提供的注册令牌无效。请确保它与客户端应用在注册 FCM 时获得的注册令牌相符。不要截断或添加其他字符。
`messaging/registration-token-not-registered`	提供的注册令牌未注册。以前有效的注册令牌可能会因多种原因而被取消注册，其中包括：客户端应用从 FCM 自行取消注册。客户端应用被自动取消注册。如果用户卸载该应用，或者在 Apple 平台中 APNs 反馈服务报告称 APNs 令牌无效，就可能会发生这种情况。注册令牌已过期。例如，Google 可能决定更新注册令牌，或 Apple 设备的 APNs 令牌可能已过期。客户端应用已更新，但新版本未配置为接收消息。对于所有这些情况，请移除此注册令牌，并停止用其发送消息。
`messaging/invalid-package-name`	消息被发送至软件包名称与提供的 `restrictedPackageName` 选项不匹配的注册令牌。
`messaging/message-rate-exceeded`	向特定目标发送消息的频率过高。请减少发送到此设备或主题的消息数，且不要立即再次尝试向此目标发送消息。
`messaging/device-message-rate-exceeded`	向特定设备发送消息的频率过高。请减少发送到此设备的消息数，且不要立即再次尝试向此设备发送消息。
`messaging/topics-message-rate-exceeded`	向特定主题的订阅者发送消息的频率过高。请减少发送到相应主题的消息数，且不要立即再次尝试向相应主题发送消息。
`messaging/too-many-topics`	注册令牌订阅的主题数量已达到上限，无法订阅更多主题。
`messaging/invalid-apns-credentials`	因为所需的 APNs SSL 证书尚未上传或已过期，所以无法向 Apple 设备发送消息。请检查您的开发和生产环境证书是否有效。
`messaging/mismatched-credential`	用于对此 SDK 进行身份验证的凭据无权向所提供的注册令牌对应的设备发送消息。请确保相应凭据和注册令牌均属于同一个 Firebase 项目。如需查看有关如何对 Firebase Admin SDK 进行身份验证的文档，请参阅将 Firebase 添加到您的应用。
`messaging/authentication-error`	SDK 无法向 FCM 服务器验证身份。请务必使用具有发送 FCM 消息相应权限的凭据对 Firebase Admin SDK 进行身份验证。如需查看有关如何对 Firebase Admin SDK 进行身份验证的文档，请参阅将 Firebase 添加到您的应用。
`messaging/server-unavailable`	FCM 服务器无法及时处理请求。您应该重试同一个请求，但必须：如果 FCM 连接服务器发出的响应中包含 `Retry-After` 标头，则应在该标头指明的间隔后重试。在您的重试机制中实现指数退避。例如，如果等待一秒钟后进行第一次重试，则至少要等待两秒钟再进行下一次重试，然后等待四秒钟，并继续增加等待时间。如果您要发送多条消息，请分别将每条消息额外延迟随机时长，从而避免同时发出所有消息的新请求。导致出现问题的发送者有可能会被列入屏蔽名单。
`messaging/internal-error`	FCM 服务器在尝试处理请求时遇到错误。您可按照之前的 `messaging/server-unavailable` 行中列出的要求重试同一请求。如果错误持续存在，请向我们的错误报告支持渠道报告该问题。
`messaging/unknown-error`	返回了未知的服务器错误。如需了解详情，请参阅错误消息中的原始服务器响应。如果您看到此错误，请向我们的错误报告支持渠道报告完整的错误消息。