从旧版FCM APIs迁移至HTTP v1时遇404请求实体未找到错误

问题重现 #

迁移至FCM HTTP v1 API后，通过设备token推送时收到如下错误：

{"error"=>{"code"=>404, "message"=>"Requested entity was not found.", "status"=>"NOT_FOUND", "details"=>[{"@type"=>"type.googleapis.com/google.firebase.fcm.v1.FcmError", "errorCode"=>"UNREGISTERED"}]}

通过topic推送正常，且这些token在旧版FCM API中可正常使用。

核心原因及解决方法 #

• 校验token格式合规性
  旧版API对token格式校验较宽松，HTTP v1要求严格遵循规范。确保token无多余空格、换行符或转义错误，直接使用客户端获取的原始字符串。

• 确认项目与权限匹配
  HTTP v1 API要求请求使用的服务账号必须与token所属Firebase项目完全绑定：

  • 检查推送请求中指定的project_id是否和token生成的项目一致
  • 确保服务账号拥有该项目的Cloud Messaging Admin或Editor权限

• 触发客户端重新获取token
  部分旧token在v1 API中被标记为未注册，可能是因为客户端长期未同步FCM服务器、或应用重装后未更新token。触发客户端调用FCM注册接口获取新token，替换旧token后重试。

• 修正请求体结构
  HTTP v1的请求体结构与旧版不同，需将目标token放在正确字段：

  {
    "message": {
      "token": "你的设备token",
      "notification": {
        "title": "测试标题",
        "body": "测试内容"
      }
    }
  }
  

  禁止使用旧版的to字段，v1版本统一通过message.token指定目标设备。

内容的提问来源于stack exchange，提问作者Talha Tariq