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 |
提供的註冊權杖未註冊。先前有效的註冊權杖可能會因各種原因取消註冊,包括:
|
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 伺服器無法及時處理要求,您應重試相同要求,但必須:
|
messaging/internal-error |
嘗試處理要求時,FCM伺服器發生錯誤。您可以按照先前 messaging/server-unavailable 列中列出的規定,重試相同要求。如果錯誤仍未解決,請透過 Bug Report 支援管道回報問題。 |
messaging/unknown-error |
系統傳回不明的伺服器錯誤。詳情請參閱錯誤訊息中的原始伺服器回應。如果收到這則錯誤訊息,請透過錯誤報告支援管道,回報完整錯誤訊息。 |