雲端 API 錯誤代碼
雲端 API 採用圖形 API 建置，因此若您對處理圖形 API 錯誤回應不熟悉，請參閱圖形 API 錯誤處理說明文件。
一般而言，建置應用程式錯誤處理邏輯時，建議以 code 值和 details 裝載屬性為主。這些屬性及其值更能指出基礎錯誤。
代碼標題在 API 錯誤回應裝載中沒有專用屬性，其包含在 message 值當中。不過，建議您不要依賴標題作為錯誤處理邏輯，因為標題最後會停用。
接收錯誤：同步與非同步
雲端 API 錯誤會以圖形 API 回應同步傳回、透過 Webhook 非同步傳回，或有時會同時透過這兩種方式傳回。
處理雲端 API 時最好同時監控圖形 API 回應和 messages Webhook 以進行錯誤處理。若您已訂閱 messages Webhook 欄位，在發生提供支援的非同步錯誤類型時，您會收到錯誤通知。
錯誤回應 Webhooks 和語法
雲端 API 錯誤可能會在下列 Webhook 物件中出現：
雲端 API
entry.changes.value.errorsentry.changes.value.messages.errors
內部部署 API
errors
錯誤回應語法
{
"error": {
"message": "<MESSAGE>",
"type": "<TYPE>",
"code": <CODE>,
"error_data": {
"messaging_product": "whatsapp",
"details": "<DETAILS>"
},
"error_subcode": <ERROR_SUBCODE>
"fbtrace_id": "<FBTRACE_ID>"
}
}錯誤回應內容
| 屬性 | 值類型 | 說明 |
|---|---|---|
| 整數 | 錯誤代碼。建議您依據錯誤代碼組建應用程式的錯誤處理功能，不要採用子代碼或 HTTP 回應狀態代碼。 |
| 字串 | 說明錯誤以及最可能的出錯原因。這項指標同時也可能包含排除錯誤的相關資訊，例如無效的參數或可以接受的值。 |
| 整數 | 已停用。不會在 16.0 以上版本的回應中傳回。 圖形 API 子代碼。並非所有回應均包含子代碼，因此建議您，建置應用程式錯誤處理邏輯時改以 |
| 字串 | 聯絡直接支援時可以註明的追蹤編號。這個編號可以幫助我們偵錯。 |
| 字串 | 錯誤代碼及代碼標題的組合。例如： |
| 字串 | 傳訊產品。雲端 API 回應的這個值一律是 |
| 字串 | 錯誤類型。 |
回應範例
{
"error": {
"message": "(#130429) Rate limit hit",
"type": "OAuthException",
"code": 130429,
"error_data": {
"messaging_product": "whatsapp",
"details": "Message failed to send because there were too many messages sent from this phone number in a short period of time"
},
"error_subcode": 2494055,
"fbtrace_id": "Az8or2yhqkZfEZ-_4Qn_Bam"
}
}
錯誤代碼
授權錯誤
| 代碼 | 說明 | 可能的解決方案 | HTTP 狀態代碼 |
|---|---|---|---|
AuthException | 我們無法驗證應用程式用戶。 | 通常這表示包含的存取權杖已經過期、失效，或者應用程式用戶已變更某項設定，不讓所有應用程式存取其資料。建議您取得新的存取權杖。 |
未授權 |
API 方法 | 功能或權限問題。 |
內部伺服器錯誤 | |
權限遭拒 | 未獲得權限或權限遭移除。 | 使用存取權杖偵錯工具確認應用程式是否已經得到端點所要求的權限。請參閱疑難排解。 請確認用於設定企業公開密鑰 的電話號碼已列���允許清單。 |
禁止 |
存取權杖已過期 | 您的存取權杖已過期。 |
未授權 | |
API 權限 | 未獲得權限或權限遭移除。 |
禁止 |
節流錯誤
| 代碼 | 說明 | 可能的解決方案 | HTTP 狀態代碼 |
|---|---|---|---|
API 發出過多呼叫 | 應用程式已經達到 API 呼叫限速。 | 在應用程式主控板中載入應用程式並查看應用程式限速部分，確認應用程式是否已經達到其限速。若已經達到，請稍後再試或減少應用程式發出 API 查詢的頻率或數量。 |
要求錯誤 |
限速問題 | WhatsApp Business 帳號已達到限速。 | 請參閱 WhatsApp Business 帳號限速。請稍後再試或減少應用程式發出 API 查詢的頻率或數量。 |
要求錯誤 |
已達到限速標準 | 已達到雲端 API 訊息傳輸量。 | 應用程式已達到 API 傳輸量限制。請參閱傳輸量。稍後再試或減少應用程式傳送訊息的頻率。 |
要求錯誤 |
已達到垃圾訊息限速 | 能使用這個電話號碼傳送的訊息數量有限，因此無法傳送訊息。可能是因為先前有太多訊息遭封鎖或標註為垃圾訊息。 | 在 WhatsApp 管理工具中查看品質狀態，並且參閱依品質決定限速說明文件，瞭解詳細資訊。 |
要求錯誤 |
達到（商業帳號，消費者帳號）組合限速 | 傳訊方電話號碼短時間內傳送太多訊息至同一個收件人電話號碼。 | 若要傳送訊息至同一個電話號碼，請稍後再重試這項操作。此時仍可傳送訊息給不同的電話號碼，不需等待 |
要求錯誤 |
超出帳號註冊取消註冊限速 | 註冊或取消註冊失敗，因為在短時間內嘗試使用此電話號碼的次數過多 | 由於已達到註冊/取消註冊嘗試限制，已封鎖該商家電話號碼。號碼解除封鎖後再試一次。請參閱註冊文件中的「限制」。 |
要求錯誤 |
整合錯誤
| 代碼 | 說明 | 可能的解決方案 | HTTP 狀態代碼 |
|---|---|---|---|
因違反政策而暫時遭到封鎖 | 與該應用程式連結的 WhatsApp Business 帳號因違反平台政策而遭限制或停用。 | 請參閱政策執行文件，瞭解違反政策相關資訊以及解決之道。 |
禁止 |
帳號遭封鎖 | 與該應用程式連結的 WhatsApp Business 帳號因違反平台政策而遭限制或停用，或者我們無法根據該 WhatsApp Business 帳號的資料集確認要求中包含的資料（例如要求中的雙階段 PIN 不正確）。 | 請參閱政策執行文件，瞭解違反政策相關資訊以及解決之道。 您也可以使用健康狀態 API，它可以提供有關帳號鎖定原因的更多洞察資訊。 |
禁止 |
其他錯誤
| 代碼 | 說明 | 可能的解決方案 | HTTP 狀態代碼 |
|---|---|---|---|
不明 API | 要求無效或可能發生伺服器錯誤。 | 請參閱 WhatsApp Business 平台狀態頁面，查看 API 狀態資訊。若沒有發生伺服器服務中斷問題，請參閱端點參考資料，確認您的要求格式正確無誤且符合所有端點條件。 |
要求錯誤 |
API 服務 | 停機或負荷過重造成的暫時情況。 | 重試之前請參閱 WhatsApp Business 平台狀態頁面，查看 API 狀態資訊。 |
無法提供服務 |
參數值無效 | 商家電話號碼遭刪除。 | 請確認商家電話號碼是否正確。 |
要求錯誤 |
無效的參數 | 要求包含了一或多項不支援或拼字錯誤的參數。 | 請參閱端點的參考資料，判斷可支援的參數及正確拼字。 設定企業公開密鑰時，請確認其為 PEM 格式的有效 2048 位元 RSA 公開密鑰。 請確認註冊中的電話號碼編號與之前儲存的電話號碼編碼兩者相符。 請確認您的參數符合該類型的任何長度限制。 |
要求錯誤 |
用戶的編號是實驗的一部分 | 在實驗過程中未傳送訊息。 | 請參閱行銷訊息實驗。 |
要求錯誤 |
發生錯誤 | 發生不明錯誤，無法傳送訊息。 設定企業公開密鑰時，無法計算簽章、無法呼叫 GraphQL 端點，或 GraphQL 端點傳回錯誤。 | 再試一次。若持續發生這個錯誤，請申請直接支援票證。 |
內部伺服器錯誤 |
存取遭拒 | 未獲得權限或權限遭移除。 |
禁止 | |
缺少必要參數 | 要求缺少必要參數。 | 請參閱端點的參考資料，判斷必要的參數。 |
要求錯誤 |
參數值無效 | 一或多個參數值無效。 | 請參閱端點的參考資料，判斷各參數支援的值，並參閱電話號碼，瞭解如何將電話號碼加入 WhatsApp Business 帳號。 |
要求錯誤 |
無法提供服務 | 暫時無法提供某項服務。 | 重試之前請參閱 WhatsApp Business 平台狀態頁面，查看 API 狀態資訊。 |
內部伺服器錯誤 |
收件人不能是傳訊方 | 傳訊方和收件人的電話號碼相同。 | 請將訊息傳送到非傳訊方的電話號碼。 |
要求錯誤 |
訊息無法送達 | 無法傳遞訊息。可能原因包括：
| 使用非 WhatsApp 通訊方式，要求 WhatsApp 用戶執行以下動作：
|
要求錯誤 |
商家資格付款問題 | 發生一個付款方式相關問題。 | 請參閱關於 WhatsApp Business 帳號收費，並且確認您設定的帳單資訊正確無誤。 常見問題：
|
要求錯誤 |
憑證不正確 | 電話號碼註冊錯誤，因此無法傳送訊息。 | 請先註冊電話號碼，再重試一次。 |
內部伺服器錯誤 |
再次互動訊息 | 收件人上次回覆傳訊方號碼的時間已經超過 24 小時。 | 改用訊息範本傳送商家主動傳送的訊息給收件人。 |
要求錯誤 |
不支援的訊息類型 | 不支援的訊息類型。 | 請先參閱訊息，瞭解可以支援的訊息類型，再使用支援的訊息類型重試。 |
要求錯誤 |
影音素材下載錯誤 | 無法下載用戶傳送的影音素材。 | 我們因為一或多個原因而無法下載影音素材，例如不支援的影音素材類型。請參閱 要求 WhatsApp 用戶使用非 WhatsApp 方法傳送媒體檔案給您。 |
要求錯誤 |
影音素材上傳錯誤 | 無法上傳訊息中使用的影音素材。 | 我們因為一或多個原因而無法上傳影音素材，例如不支援的影音素材類型。請參閱 建議您檢查所有導致錯誤的媒體檔案，並確認檔案確實受支援。 例如，在 UNIX 中，您可以透過指令行使用檔案檢查來確定其 MIME 類型：
接著您可以確認其 MIME 類型是否列在我們的支援媒體類型清單中。 為了在傳送影音素材時獲得更可靠的效能，請參閱影音素材 HTTP 快取和上傳影音素材。 |
要求錯誤 |
帳號處於維護模式 | 商業帳號處於維護模式 | WhatsApp Business 帳號處於維護模式。發生此狀況的原因之一可能是帳號正在進行傳輸量升級。 |
要求錯誤 |
範本參數數目不符 | 要求中包含的變數參數值數目與範本中定義的變數參數值數目不相符。 | 請參閱訊息範本準則，確認要求包含範本中定義的所有變數參數值。 |
要求錯誤 |
範本不存在 | 指定語言沒有此範本，或者範本尚未申請獲准。 | 請確認您的範本已經申請獲准，且範本的名稱和語言地區設定正確。請務必遵守訊息範本準則。 |
找不到 |
範本的合成文字太長 | 譯文太長。 | 查看 WhatsApp 管理工具，確認範本已翻譯。請參閱品質評分與範本狀態。 |
要求錯誤 |
範本格式違反字元政策 | 範本內容違反 WhatsApp 政策。 | 請參閱拒絕原因，判斷違規內容的可能原因。 |
要求錯誤 |
範本參數格式不符 | 變數參數值格式不正確。 | 要求中包含的變數參數值未使用範本指定的格式。請參閱訊息範本準則。 |
要求錯誤 |
範本遭暫停 | 範本因為品質不佳而遭暫停，所以無法以訊息範本傳送。 | 請編輯範本以改善品質，通過審查後再試一次。 |
要求錯誤 |
範本遭停用 | 範本因為品質不佳而遭到多次暫停，現在已永久停用。 | 請以不同的內容建立新範本。 |
要求錯誤 |
流程遭封鎖 | 流程處於封鎖狀態。 | 修正流程 |
要求錯誤 |
流程遭限速 | 流程處於限速狀態，在過去一小時內已經傳送 10 則使用此流程的訊息。 | 修正流程 |
要求錯誤 |
撤銷註冊不完整 | 之前嘗試撤銷註冊不成功。 |
內部伺服器錯誤 | |
暫時無法使用伺服器 | 暫時無法使用伺服器。 | 重試之前請參閱 WhatsApp Business 平台狀態頁面並查看 API 狀態資訊，接著查看回應的 |
無法提供服務 |
雙步驟驗證 PIN 不符 | 雙步驟驗證 PIN 不正確。 | 確認要求所含的雙步驟驗證 PIN 正確無誤。 重設雙步驟驗證 PIN： |
要求錯誤 |
需再次驗證電話號碼 | 需驗證電話號碼才能註冊。 | 請先驗證電話號碼再進行註冊。 |
要求錯誤 |
雙步驟驗證 PIN 輸入次數太多 | 使用這個電話號碼輸入雙步驟驗證 PIN 的次數太多。 | 請等到 |
要求錯誤 |
雙步驟驗證 PIN 輸入速度太快 | 輸入雙步驟驗證 PIN 的速度太快。 | 再試一次之前請先檢查 |
要求錯誤 |
這是尚未註冊的電話號碼 | 尚未在 WhatsApp Business 平台註冊這個電話號碼。 | 請先註冊電話號碼，再重試一次。 |
要求錯誤 |
請稍待幾分鐘，再嘗試註冊此電話號碼 | 您嘗試註冊的電話號碼近期遭到刪除，且刪除程序尚未完成。 | 請稍待 5 分鐘，再重新嘗試要求。 |
要求錯誤 |
一般用戶錯誤 | 要求參數發生不明錯誤，無法傳送訊息。 |
要求錯誤 |