Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

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` 類型的擴充功能，指定無效的欄位。	可能原因包括註冊無效、套件名稱無效、訊息過大、資料金鑰無效、存留時間無效或其他參數無效。註冊無效：請檢查傳送至伺服器的註冊權杖格式。請確認這組權杖與用戶端應用程式向 FCM 註冊時收到的註冊權杖相符。請勿截斷權杖或加入其他字元。套件名稱無效：請確認訊息傳送對象的註冊權杖，其套件名稱與要求中傳遞的值相符。訊息過大：請確認訊息中包含的酬載資料總大小未超過 FCM 限制：大多數訊息為 4096 位元組，主題訊息則為 2048 位元組。包括鍵和值。資料鍵無效：請確認酬載資料不含 FCM 內部使用的鍵 (例如 from、gcm 或任何以 google 為前置字元的值)。請注意，FCM 也會使用某些字詞 (例如 collapse_key)，但允許在酬載中使用，在這種情況下，酬載值會由 FCM 值覆寫。存留時間無效：請確認 ttl 使用的值為整數，代表介於 0 到 2,419,200 秒 (4 週) 之間的時間長度。參數無效：請確認提供的參數名稱和類型正確。
`UNREGISTERED` (HTTP 錯誤代碼 = 404) 應用程式執行個體已從 FCM 取消註冊。這通常表示使用的權杖已失效，必須使用新的權杖。	這可能是因為缺少註冊權杖，或權杖未註冊。 Missing Registration：如果訊息目標是 `token` 值，請確認要求包含註冊權杖。未註冊：現有的註冊權杖可能會在多種情況下失效，包括： - 用戶端應用程式取消註冊 FCM。 - 如果用戶端應用程式自動取消註冊，這可能是因為使用者解除安裝應用程式。舉例來說，在 iOS 上，如果 APNs 回饋服務回報 APNs 權杖無效，就會發生這種情況。 - 註冊權杖過期 (例如 Google 決定重新整理註冊權杖，或 iOS 裝置的 APNs 權杖過期)。 - 用戶端應用程式已更新，但新版本未設定接收訊息。在上述所有情況下，請從應用程式伺服器中移除這個註冊權杖，並停止使用該權杖傳送訊息。
`SENDER_ID_MISMATCH` (HTTP 錯誤代碼 = 403) 經驗證的寄件者 ID 與註冊權杖的寄件者 ID 不同。	註冊權杖會與特定寄件者群組連結。用戶端應用程式註冊 FCM 時，必須指定允許傳送訊息的寄件者。傳送訊息至用戶端應用程式時，請使用其中一個傳送者 ID。如果改用其他傳送者，現有的註冊權杖將無法運作。
`QUOTA_EXCEEDED` (HTTP 錯誤代碼 = 429) 訊息目標的傳送上限已超過。系統會傳回 `google.rpc.QuotaFailure` 類型的擴充功能，指定超出哪項配額。	這項錯誤可能是因為超出訊息頻率配額、裝置訊息頻率配額或主題訊息頻率配額。 Message rate exceeded：訊息傳送頻率過高。請降低整體訊息傳送頻率。使用指數輪詢，並將初始延遲時間設為至少 1 分鐘，重試遭拒的訊息。超出裝置訊息頻率：傳送至特定裝置的訊息頻率過高。請參閱單一裝置的訊息頻率限制。請減少傳送至這部裝置的訊息數量，並使用指數輪詢重試傳送。主題訊息頻率過高：傳送給特定主題訂閱者的訊息頻率過高。請減少這個主題傳送的訊息數量，並以指數輪詢方式重試傳送，初始延遲時間至少為 1 分鐘。
`UNAVAILABLE` (HTTP 錯誤代碼 = 503) 伺服器超載。	伺服器無法及時處理要求。重試相同要求，但必須： - 遵循 Retry-After 標頭 (如果 FCM 連線伺服器的回應中包含該標頭)。 - 在重試機制中實作指數輪詢。(例如，如果您在第一次重試前等待一秒，請在下次重試前等待至少兩秒，然後等待 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 取消註冊。用戶端應用程式已自動取消註冊。如果使用者解除安裝應用程式，或在 Apple 平台上，APNs 意見回饋服務回報 APNs 權杖無效，就可能發生這種情況。註冊權杖已過期。舉例來說，Google 可能會決定重新整理註冊權杖，或 Apple 裝置的 APN 權杖可能已過期。用戶端應用程式已更新，但新版本未設為接收訊息。在上述所有情況下，請移除這個註冊權杖，並停止使用該權杖傳送訊息。
`messaging/invalid-package-name`	訊息傳送至註冊權杖，但其套件名稱與提供的 `restrictedPackageName` 選項不符。
`messaging/message-rate-exceeded`	傳送至特定目標的訊息頻率過高。請減少傳送至這個裝置或主題的訊息數量，且不要立即重試傳送至這個目標。
`messaging/device-message-rate-exceeded`	傳送至特定裝置的訊息頻率過高。請減少傳送至這部裝置的訊息數量，且不要立即重試傳送至這部裝置。
`messaging/topics-message-rate-exceeded`	傳送給特定主題訂閱者的訊息頻率過高。減少傳送至該主題的訊息數量，且不要立即重試傳送至該主題。
`messaging/topics-subscription-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 伺服器進行驗證。請務必使用具備適當權限的憑證驗證 Firebase Admin SDK，以便傳送 FCM 訊息。如要瞭解如何驗證 Firebase Admin SDK，請參閱「在應用程式中新增 Firebase」一文。
`messaging/server-unavailable`	FCM 伺服器無法及時處理要求。您應重試相同要求，但必須：如果 FCM 連線伺服器的回應中包含 `Retry-After` 標頭，請遵循該標頭。在重試機制中實作指數輪詢。舉例來說，如果您在第一次重試前等待一秒，則在下次重試前至少等待兩秒，然後等待四秒，並繼續提高秒數間隔。如要傳送多則訊息，請為每則訊息分別延遲額外的隨機時間，避免同時為所有訊息發出新要求。如果寄件者造成問題，可能會遭到封鎖。
`messaging/internal-error`	FCM 伺服器嘗試處理要求時發生錯誤。您可以按照先前 `messaging/server-unavailable` 列中列出的規定，重試相同要求。如果錯誤持續發生，請透過錯誤報告支援管道回報問題。
`messaging/unknown-error`	傳回不明的伺服器錯誤。如要瞭解詳情，請查看錯誤訊息中的原始伺服器回應。如果收到這則錯誤訊息，請透過錯誤報告支援管道回報完整的錯誤訊息。

FCM 錯誤代碼 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

HTTP v1 API 的 REST 錯誤代碼

範例 1：HTTP v1 API 要求傳回錯誤回應，資料訊息中的值無效

範例 2：HTTP v1 API 要求因註冊權杖無效而傳回錯誤回應

Admin SDK 錯誤代碼

FCM 錯誤代碼