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`	系統傳回不明的伺服器錯誤。詳情請參閱錯誤訊息中的原始伺服器回應。如果收到這則錯誤訊息，請透過錯誤報告支援管道，回報完整錯誤訊息。