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」 type.googleapis.com/google.rpc.BadRequest,表示要求值有錯誤。第二個範例 (類型為 type.googleapis.com/google.firebase.fcm.v1.FcmError) 含有 FCM 專屬錯誤。對於許多錯誤,詳細資料陣列會包含您偵錯和找出解決方案所需的資訊。

下表列出 FCM 第 1 版 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 中使用的值是介於 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 標頭,請遵守該標頭的規定。
- 在重試機制中實作指數輪詢。(例如,如果您在第一次重試前等待了一秒,請在下一次重試前等待至少兩秒,然後等待 4 秒,依此類推)。如果傳送多則訊息,請考慮套用抖動。詳情請參閱「處理重試,或查看 FCM 狀態資訊主頁,判斷是否有任何持續的服務中斷情形影響 FCM。如果寄件者造成問題,可能會遭到拒絕列入許可清單。
INTERNAL (HTTP 錯誤代碼 = 500) 發生不明的內部錯誤。 伺服器嘗試處理要求時發生錯誤,您可以按照「處理重試 中的建議重試相同要求,或是查看 FCM 狀態資訊主頁。找出影響 FCM 的服務中斷問題。如果錯誤持續發生,請與 Firebase 支援團隊聯絡。
THIRD_PARTY_AUTH_ERROR (HTTP 錯誤代碼 = 401) APNs 憑證或網頁推送授權金鑰無效或遺失。 無法傳送指定傳送至 iOS 裝置或網頁推送註冊的訊息。檢查開發和正式版憑證是否有效。

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 取消註冊。
  • 用戶端應用程式已自動取消註冊。如果使用者解除安裝應用程式,或是 APNs 意見回饋服務回報 APNs 權杖無效 (適用於 Apple 平台),就可能發生這種情況。
  • 註冊權杖已過期。舉例來說,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 由於未上傳或已過期,因此無法傳送以 Apple 裝置為目標的訊息。檢查開發和正式版憑證是否有效。
messaging/mismatched-credential 用來驗證這個 SDK 的憑證沒有權限,無法將訊息傳送至與所提供註冊權杖相應的裝置。確認憑證和註冊權杖都屬於同一個 Firebase 專案。如需驗證 Firebase Admin SDK 的說明文件,請參閱「將 Firebase 新增至應用程式」。
messaging/authentication-error SDK 無法向 FCM 伺服器進行驗證。請務必使用具備適當權限的憑證驗證 Firebase Admin SDK,以便傳送 FCM 訊息。如需驗證 Firebase Admin SDK 的說明文件,請參閱「將 Firebase 新增至應用程式」。
messaging/server-unavailable FCM 伺服器無法及時處理要求,您應重試相同要求,但必須:
  • 如果 FCM 連線伺服器的回應中包含 Retry-After 標頭,請遵守該標頭的規定。
  • 在重試機制中實作指數輪詢。舉例來說,如果第一次重試前等待了一秒,下一次重試前至少要等待兩秒,然後是四秒,並持續增加秒數間隔。如要傳送多則訊息,請為每則訊息額外隨機延遲一段時間,以免同時為所有訊息發出新要求。
造成問題的寄件者可能會遭到封鎖。
messaging/internal-error 嘗試處理要求時,FCM伺服器發生錯誤。您可以按照先前 messaging/server-unavailable 列中列出的規定,重試相同要求。如果錯誤仍未解決,請透過 Bug Report 支援管道回報問題。
messaging/unknown-error 系統傳回不明的伺服器錯誤。詳情請參閱錯誤訊息中的原始伺服器回應。如果收到這則錯誤訊息,請透過錯誤報告支援管道,回報完整錯誤訊息。