雲端 API 錯誤代碼
雲端 API 建基於 Graph API，因此，如果您不熟悉如何處理 Graph API 錯誤回應，請參閱 Graph API 錯誤處理文件。
一般來說，我們建議您就著 code 值和 details 裝載屬性建構應用程式的錯誤處理邏輯。這類屬性及其值更能反映出深層的錯誤。
錯誤代碼標題在 API 錯誤回應裝載中沒有專門的屬性，而是包含在 message 值當中。不過，我們建議您不要依賴代碼標題來建構錯誤處理邏輯，因為代碼標題最終會被停用。
接收錯誤：同步和非同步
雲端 API 錯誤會作為 Graph API 回應以同步形式傳回，或透過 Webhook 以非同步形式傳回，有時亦會同時透過這兩種方式傳回。
使用雲端 API 時，不妨同時監察 Graph 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 回應狀態代碼）來建構自家應用程式的錯誤處理邏輯。 |
| 字串 | 有關錯誤本身以及最可能導致其出現的原因之說明。可能還包含有關如何處理錯誤的資訊，例如哪個參數無效或可接受哪些值。 |
| 整數 | 已停用。不會在 v16.0 或更新版本的回應中傳回。 Graph 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 狀態代碼 |
|---|---|---|---|
驗證異常 | 我們無法驗證相關應用程式用戶。 | 通常，這表示包含的存取憑證已過期或失效，或是應用程式用戶為防止所有應用程式存取自己的資料而更改了設定。我們建議您憑證索取新的存取憑證。 |
未授權 |
API 方法 | 功能或權限問題。 |
內部伺服器錯誤 | |
權限被拒 | 未獲授予權限或權限已遭移除。 | 使用存取憑證除錯工具來確認您的應用程式已獲授予端點所要求的權限。請參閱解決疑難。 請確保已將用於設定企業公開金鑰的手機號碼列入允許清單。 |
禁止 |
存取憑證已過期 | 您的存取憑證已過期。 |
未授權 | |
API 權限 | 未獲授予權限或權限已遭移除。 |
禁止 |
限速錯誤
| 代碼 | 說明 | 可行解決方案 | HTTP 狀態代碼 |
|---|---|---|---|
API 太多呼叫 | 應用程式已達到其 API 呼叫限速限制。 | 在應用程式管理中心中載入此應用程式，然後查看應用程式限速區塊，以確認此應用程式已達到其限速額度。如果已達到，請稍後重試，或減少此應用程式發出 API 查詢的頻率或次數。 |
錯誤要求 |
限速問題 | WhatsApp Business 帳戶已達到其限速額度。 | 請參閱 WhatsApp Business 帳戶的限速規定。請稍後重試，或減少此應用程式發出 API 查詢的頻率或次數。 |
錯誤要求 |
達到限速額度 | 已達到雲端 API 訊息輸送量。 | 應用程式已達到 API 的輸送量限制。請參閱輸送量。請稍後重試，或減少此應用程式傳送訊息的頻率。 |
錯誤要求 |
達到垃圾訊息限速 | 此電話號碼可傳送的訊息數量受限，因此無法傳送訊息。這可能是之前有太多訊息被封鎖或被標記為垃圾訊息所致。 | 在 WhatsApp 管理工具中查看您的品質狀態，然後參閱根據品質而定的限速規定文件來了解詳情。 |
錯誤要求 |
達到（商業帳戶、消費者帳戶）配對限速額度 | 在短時間內有過多訊息從傳送方電話號碼傳送到同一個傳送對象電話號碼。 | 如需傳送訊息到同一個手機號碼，請稍等再重試。您仍可傳送訊息到其他電話號碼，而無需等待 |
錯誤要求 |
帳戶註冊或取消註冊率超出限制 | 短時間內太多次嘗試註冊或取消註冊此電話號碼，導致無法註冊或取消註冊 | 此商家電話號碼因達到註冊／取消註冊的嘗試次數上限而遭到封鎖。號碼解除封鎖後，請再試一次。請查看註冊程序文件的「限制」部分。 |
錯誤要求 |
完整性錯誤
| 代碼 | 說明 | 可行解決方案 | HTTP 狀態代碼 |
|---|---|---|---|
因違反政策規定而暫時被封鎖 | 由於違反平台政策，與應用程式連結的 WhatsApp Business 帳戶已被限制或停用。 | 請參閱政策執行文件，了解政策違規內容及相應解決方案。 |
禁止 |
商業帳戶被限制向此國家／地區的用戶傳送訊息。 | 此 WhatsApp Business 帳戶被限制，不能向某些國家／地區的用戶傳送訊息。 | 請參閱《WhatsApp Business 訊息政策》，進一步了解您業務類別的允許收發訊息國家／地區。 |
禁止 |
帳戶被鎖定 | 由於違反平台政策，與應用程式連結的 WhatsApp Business 帳戶已被限制或停用，或者我們無法根據 WhatsApp Business 帳戶的資料集來驗證要求中包含的資料（例如，要求中包含的雙重驗證 PIN 碼不正確）。 | 請參閱政策執行文件，了解政策違規內容及相應解決方案。 您還可以使用健康狀態 API，此 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 小時。 | 請改用訊息範本向傳送對象傳送商家發起的訊息。 |
錯誤要求 |
Meta 選擇了不送達訊息。 | 為保持健康的生態系統互動，這則訊息未被送達。 | 如果您收到此錯誤代碼，並懷疑是因受到限制而出現此代碼，請勿立即重試。限制可能會在不同時段生效，因此您可隔久一點再重試，直至訊息送達為止。 詳情請參閱每位用戶的營銷範本訊息限制。 |
錯誤要求 |
不支援的訊息類型 | 不支援的訊息類型。 | 請參閱訊息，了解支援的訊息類型，然後使用支援的訊息類型再試一次。 |
錯誤要求 |
媒體下載錯誤 | 無法下載用戶傳送的媒體。 | 無法下載 WhatsApp 用戶訊息中包含的媒體。詳情請參閱收到此訊息時觸發的任何訊息 Webhooks 中包含的 請 WhatsApp 用戶以 WhatsApp 以外的方式向您傳送媒體檔案。 |
錯誤要求 |
媒體上載錯誤 | 無法上載訊息中使用的媒體。 | 由於一個或多個原因，我們無法上載媒體，例如媒體為不支援的媒體類型。 詳情請參閱此訊息傳送失敗時觸發的任何訊息 Webhooks 中包含的 建議您檢查造成錯誤的任何媒體檔案，確認其實際上是否屬於支援的媒體類型。例如，在 UNIX 中，您可以透過指令行使用檔案檢查，來確定檔案的 MIME 類型：
您可據此確認是否支援此 MIME 類型。請參閱支援的媒體類型。 |
錯誤要求 |
帳戶處於維修保養模式 | 企業帳戶處於維修保養模式 | WhatsApp Business 帳戶處於維修保養模式。原因之一可能是此帳戶正在接受輸送量升級。 |
錯誤要求 |
範本參數數量不符 | 要求中包含的變數參數值數量與範本中定義的變數參數數量不相符。 | 請參閱訊息範本守則，確保要求包含範本中定義的所有變數參數值。 |
錯誤要求 |
範本不存在 | 範本不設特定語言版本，或者尚未通過審查。 | 請確保您的範本已通過審查，且範本的名稱和語言設定準確無誤。請確保遵循訊息範本守則。 |
找不到任何資料 |
範本填入文字過長 | 翻譯文字過長。 | 請查看 WhatsApp 管理工具，以確認範本經已翻譯。請參閱品質評分和範本狀態。 |
錯誤要求 |
違反範本格式字元政策 | 範本內容違反了 WhatsApp 政策。 | 請參閱未通過審查的原因，確定違規的可能原因。 |
錯誤要求 |
範本參數格式不符 | 變數參數值格式不正確。 | 要求中包含的變數參數值未使用範本中指定的格式。請參閱訊息範本守則。 |
錯誤要求 |
範本已暫停 | 範本因低品質而被暫停，因此無法在範本訊息中傳送此範本。 | 編輯範本以提升品質，並在通過核准後再次嘗試。 |
錯誤要求 |
範本已停用 | 範本因低品質而被多次暫停，現被永久停用。 | 使用不同內容建立新範本。 |
錯誤要求 |
流程已封鎖 | 流程處於封鎖狀態。 | 更正流程 |
錯誤要求 |
流程已限速 | 流程處於限速狀態，過去 1 小時內已使用此流程傳送 10 則訊息。 | 更正流程 |
錯誤要求 |
註銷未完成 | 之前的註銷嘗試失敗。 |
內部伺服器錯誤 | |
伺服器暫時無法使用 | 伺服器暫時無法使用。 | 請先查看 WhatsApp Business 平台狀態頁面，在了解 API 狀態資訊並檢查回應 |
無法提供此服務 |
雙重驗證 PIN 碼不符 | 雙重驗證 PIN 碼不正確。 | 確認要求中包含的雙重驗證 PIN 碼正確。 若要重設雙重驗證 PIN 碼，請按照下列步驟操作： |
錯誤要求 |
需要重新驗證電話號碼 | 需要驗證電話號碼才能進行註冊。 | 驗證電話號碼後再註冊。 |
錯誤要求 |
雙重驗證 PIN 碼輸入錯誤次數過多 | 此電話號碼的雙重驗證 PIN 碼輸入錯誤次數過多。 | 請在 |
錯誤要求 |
過快輸入雙重驗證 PIN 碼 | 過快輸入雙重驗證 PIN 碼。 | 請先查看 |
錯誤要求 |
電話號碼未註冊 | 未在 WhatsApp Business 平台上註冊電話號碼。 | 請先註冊電話號碼再重試。 |
錯誤要求 |
請等待幾分鐘，然後再嘗試註冊此手機號碼 | 您正在嘗試註冊的電話號碼近期被刪除，但刪除尚未完成。 | 請等待 5 分鐘，然後再重新嘗試傳送要求。 |
錯誤要求 |
一般用戶錯誤 | 您的要求參數出現未知錯誤，因此無法傳送訊息。 |
錯誤要求 |