雲端 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.errors
  • entry.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>"
  }
}

錯誤回應內容

屬性 值類型 說明

code

整數

錯誤代碼。建議您依據錯誤代碼組建應用程式的錯誤處理功能,不要採用子代碼或 HTTP 回應狀態代碼。

details

字串

說明錯誤以及最可能的出錯原因。這項指標同時也可能包含排除錯誤的相關資訊,例如無效的參數或可以接受的值。

error_subcode

整數

已停用。不會在 16.0 以上版本的回應中傳回。


圖形 API 子代碼。並非所有回應均包含子代碼,因此建議您,建置應用程式錯誤處理邏輯時改以 codedetails 屬性為主。

fbtrace_id

字串

聯絡直接支援時可以註明的追蹤編號。這個編號可以幫助我們偵錯。

message

字串

錯誤代碼及代碼標題的組合。例如:(#130429) Rate limit hit

messaging_product

字串

傳訊產品。雲端 API 回應的這個值一律是 WhatsApp 字串。

type

字串

錯誤類型。

回應範例

{
  "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 狀態代碼

0

AuthException

我們無法驗證應用程式用戶。

通常這表示包含的存取權杖已經過期、失效,或者應用程式用戶已變更某項設定,不讓所有應用程式存取其資料。建議您取得新的存取權杖

401

未授權

3

API 方法

功能或權限問題。

使用存取權杖偵錯工具確認應用程式是否已經得到端點所要求的權限。請參閱疑難排解

500

內部伺服器錯誤

10

權限遭拒

未獲得權限或權限遭移除。

使用存取權杖偵錯工具確認應用程式是否已經得到端點所要求的權限。請參閱疑難排解

請確認用於設定企業公開密鑰 的電話號碼已列入允許清單。

403

禁止

190

存取權杖已過期

您的存取權杖已過期。

取得新的存取權杖

401

未授權

200-299

API 權限

未獲得權限或權限遭移除。

使用存取權杖偵錯工具確認應用程式是否已經得到端點所要求的權限。請參閱疑難排解

403

禁止

節流錯誤

代碼 說明 可能的解決方案 HTTP 狀態代碼

4

API 發出過多呼叫

應用程式已經達到 API 呼叫限速。

應用程式主控板中載入應用程式並查看應用程式限速部分,確認應用程式是否已經達到其限速。若已經達到,請稍後再試或減少應用程式發出 API 查詢的頻率或數量。

400

要求錯誤

80007

限速問題

WhatsApp Business 帳號已達到限速。

請參閱 WhatsApp Business 帳號限速。請稍後再試或減少應用程式發出 API 查詢的頻率或數量。

400

要求錯誤

130429

已達到限速標準

已達到雲端 API 訊息傳輸量。

應用程式已達到 API 傳輸量限制。請參閱傳輸量。稍後再試或減少應用程式傳送訊息的頻率。

400

要求錯誤

131048

已達到垃圾訊息限速

能使用這個電話號碼傳送的訊息數量有限,因此無法傳送訊息。可能是因為先前有太多訊息遭封鎖或標註為垃圾訊息。

在 WhatsApp 管理工具中查看品質狀態,並且參閱依品質決定限速說明文件,瞭解詳細資訊。

400

要求錯誤

131056

達到(商業帳號,消費者帳號)組合限速

傳訊方電話號碼短時間內傳送太多訊息至同一個收件人電話號碼。

若要傳送訊息至同一個電話號碼,請稍後再重試這項操作。此時仍可傳送訊息給不同的電話號碼,不需等待

400

要求錯誤

133016

超出帳號註冊取消註冊限速

註冊或取消註冊失敗,因為在短時間內嘗試使用此電話號碼的次數過多

由於已達到註冊/取消註冊嘗試限制,已封鎖該商家電話號碼。號碼解除封鎖後再試一次。請參閱註冊文件中的「限制」。

400

要求錯誤

整合錯誤

代碼 說明 可能的解決方案 HTTP 狀態代碼

368

因違反政策而暫時遭到封鎖

與該應用程式連結的 WhatsApp Business 帳號因違反平台政策而遭限制或停用。

請參閱政策執行文件,瞭解違反政策相關資訊以及解決之道。

403

禁止

130497

商業帳號在此國家/地區受到限制,無法傳送訊息給用戶。

WhatsApp 商業帳號在某些國家/地區受到限制,無法傳送訊息給用戶。

如需有關您的商家類別中允許傳送訊息的國家/地區的詳細資訊,請參閱 WhatsApp Business 訊息政策

403

禁止

131031

帳號遭封鎖

與該應用程式連結的 WhatsApp Business 帳號因違反平台政策而遭限制或停用,或者我們無法根據該 WhatsApp Business 帳號的資料集確認要求中包含的資料(例如要求中的雙階段 PIN 不正確)。

請參閱政策執行文件,瞭解違反政策相關資訊以及解決之道。


您也可以使用健康狀態 API,它可以提供有關帳號鎖定原因的更多洞察資訊。

403

禁止

其他錯誤

代碼 說明 可能的解決方案 HTTP 狀態代碼

1

不明 API

要求無效或可能發生伺服器錯誤。

請參閱 WhatsApp Business 平台狀態頁面,查看 API 狀態資訊。如果沒有發生伺服器服務中斷問題,請參閱端點參考資料,確認您的要求格式正確無誤且符合所有端點條件。

400

要求錯誤

2

API 服務

停機或負荷過重造成的暫時情況。

重試之前請參閱 WhatsApp Business 平台狀態頁面,查看 API 狀態資訊。

503

無法提供服務

33

參數值無效

商家電話號碼遭刪除。

請確認商家電話號碼是否正確。

400

要求錯誤

100

無效的參數

要求包含了一或多項不支援或拼字錯誤的參數。

請參閱端點的參考資料,判斷可支援的參數及正確拼字。

設定企業公開密鑰時,請確認其為 PEM 格式的有效 2048 位元 RSA 公開密鑰

請確認註冊中的電話號碼編號與之前儲存的電話號碼編碼兩者相符。

請確認您的參數符合該類型的任何長度限制。

400

要求錯誤

130472

用戶的編號是實驗的一部分

實驗過程中未傳送訊息。

請參閱行銷訊息實驗

400

要求錯誤

131000

發生錯誤

發生不明錯誤,無法傳送訊息。

設定企業公開密鑰時,無法計算簽章、無法呼叫 GraphQL 端點,或 GraphQL 端點傳回錯誤。

再試一次。若持續發生這個錯誤,請申請直接支援票證。

500

內部伺服器錯誤

131005

存取遭拒

未獲得權限或權限遭移除。

使用存取權杖偵錯工具確認應用程式是否已經得到端點所要求的權限。請參閱疑難排解

403

禁止

131008

缺少必要參數

要求缺少必要參數。

請參閱端點的參考資料,判斷必要的參數。

400

要求錯誤

131009

參數值無效

一或多個參數值無效。

請參閱端點的參考資料,判斷各參數支援的值,並參閱電話號碼,瞭解如何將電話號碼加入 WhatsApp Business 帳號。

400

要求錯誤

131016

無法提供服務

暫時無法提供某項服務。

重試之前請參閱 WhatsApp Business 平台狀態頁面,查看 API 狀態資訊。

500

內部伺服器錯誤

131021

收件人不能是傳訊方

傳訊方和收件人的電話號碼相同。

請將訊息傳送到非傳訊方的電話號碼。

400

要求錯誤

131026

訊息無法送達

無法傳遞訊息。可能原因包括:

  • 收件人的電話號碼不是 WhatsApp 電話號碼。
  • 驗證範本傳送至電話國碼/區碼為 +91(印度)的 WhatsApp 用戶。驗證範本目前無法傳送給印度的 WhatsApp 用戶。
  • 收件人尚未接受我們新的《服務條款》和《隱私政策》。
  • 收件人使用舊版 WhatsApp,必須使用下列 WhatsApp 版本或更新版本:
    • Android:2.21.15.15
    • SMBA:2.21.15.15
    • iOS:2.21.170.4
    • SMBI:2.21.170.4
    • KaiOS:2.2130.10
    • Web:2.2132.6

使用非 WhatsApp 通訊方式,要求 WhatsApp 用戶執行以下動作:

  • 確認用戶確實可向您的 WhatsApp Business 電話號碼傳送訊息。
  • 確認用戶已接受我們最新的服務條款(設定 > 說明設定 > 應用程式資訊將提示用戶接受最新的服務條款/政策(如果尚未接受))
  • 更新至最新版本的 WhatsApp 用戶端。

400

要求錯誤

131042

商家資格付款問題

發生一個付款方式相關問題。

請參閱關於 WhatsApp Business 帳號收費,並且確認您設定的帳單資訊正確無誤。

常見問題:

  • WhatsApp Business 帳號未註明付款帳號
  • 信用額度超出限制
  • 未設定或啟用信用額度(付款帳號)
  • WhatsApp Business 帳號遭刪除
  • WhatsApp Business 帳號遭停權
  • 未設定時區
  • 未設定幣別
  • MessagingFor 要求(代表)處理中或已遭拒
  • 超過對話免費層級門檻且未提供有效的付款方式

400

要求錯誤

131045

憑證不正確

電話號碼註冊錯誤,因此無法傳送訊息。

請先註冊電話號碼,再重試一次。

500

內部伺服器錯誤

131047

再次互動訊息

收件人上次回覆傳訊方號碼的時間已經超過 24 小時。

改用訊息範本傳送商家主動傳送的訊息給收件人。

400

要求錯誤

131049

Meta 選擇不傳遞。

為維持健康的生態系統互動,未傳遞此訊息。

如果您有收到此錯誤代碼並懷疑是因為限制所造成,請不要立即重試。您應等待更長的時間後再重試,直到訊息送達為止,因為該限制可能在不同的時段內有效。

如需其他資訊,請參閱每用戶行銷範本訊息限制

400

要求錯誤

131051

不支援的訊息類型

不支援的訊息類型。

請先參閱訊息,瞭解可以支援的訊息類型,再使用支援的訊息類型重試。

400

要求錯誤

131052

影音素材下載錯誤

無法下載用戶傳送的影音素材。

我們無法下載 WhatsApp 用戶訊息中隨附的影音素材。如需詳細資訊,請參閱收到此訊息時觸發的任何訊息 Webhooks 中的 error.error_data.details 值。

要求 WhatsApp 用戶使用非 WhatsApp 方法傳送影音素材檔案給您。

400

要求錯誤

131053

影音素材上傳錯誤

無法上傳訊息中使用的影音素材。

我們因為一或多個原因而無法上傳影音素材,例如不支援的影音素材類型。

如需詳細資訊,請參閱此訊息無法傳送時觸發的任何訊息 Webhooks 中的 error.error_data.details 值。

建議您檢查所有導致錯誤的影音素材檔案,並確認這些檔案確實受到支援。例如,在 UNIX 中,您可以透過指令行使用檔案檢查來確定其 MIME 類型:

file -I rejected-file.mov

接著,您就可以確認其 MIME 類型是否受到支援。請參閱支援的影音素材類型

400

要求錯誤

131057

帳號處於維護模式

商業帳號處於維護模式

WhatsApp Business 帳號處於維護模式。發生此狀況的原因之一可能是帳號正在進行傳輸量升級。

500

要求錯誤

132000

範本參數數目不符

要求中包含的變數參數值數目與範本中定義的變數參數值數目不相符。

請參閱訊息範本準則,確認要求包含範本中定義的所有變數參數值。

400

要求錯誤

132001

範本不存在

指定語言沒有此範本,或者範本尚未申請獲准。

請確認您的範本已經申請獲准,且範本的名稱和語言地區設定正確。請務必遵守訊息範本準則

404

找不到

132005

範本的合成文字太長

譯文太長。

查看 WhatsApp 管理工具,確認範本已翻譯。請參閱品質評分與範本狀態

400

要求錯誤

132007

範本格式違反字元政策

範本內容違反 WhatsApp 政策。

請參閱拒絕原因,判斷違規內容的可能原因。

400

要求錯誤

132012

範本參數格式不符

變數參數值格式不正確。

要求中包含的變數參數值未使用範本指定的格式。請參閱訊息範本準則

400

要求錯誤

132015

範本遭暫停

範本因為品質不佳而遭暫停,所以無法以訊息範本傳送。

編輯範本以改善品質,通過審查後再試一次。

400

要求錯誤

132016

範本遭停用

範本因為品質不佳而遭到多次暫停,現在已永久停用。

請以不同的內容建立新範本。

400

要求錯誤

132068

流程遭封鎖

流程處於封鎖狀態。

修正流程

400

要求錯誤

132069

流程遭限速

流程處於限速狀態,在過去一小時內已經傳送 10 則使用此流程的訊息。

修正流程

400

要求錯誤

133000

撤銷註冊不完整

之前嘗試撤銷註冊不成功。

請先再次取消註冊該號碼再註冊

500

內部伺服器錯誤

133004

暫時無法使用伺服器

暫時無法使用伺服器。

重試之前請參閱 WhatsApp Business 平台狀態頁面並查看 API 狀態資訊,接著查看回應的 details 值。

503

無法提供服務

133005

雙步驟驗證 PIN 不符

雙步驟驗證 PIN 不正確。

確認要求所含的雙步驟驗證 PIN 正確無誤。


重設雙步驟驗證 PIN:


  1. 停用雙步驟驗證
  2. 傳送包含新 PIN 的 POST 要求至電話號碼端點。

400

要求錯誤

133006

需再次驗證電話號碼

需驗證電話號碼才能註冊。

請先驗證電話號碼再進行註冊。

400

要求錯誤

133008

雙步驟驗證 PIN 輸入次數太多

使用這個電話號碼輸入雙步驟驗證 PIN 的次數太多。

請等到 details 回應值所指定的時間過後再試一次。

400

要求錯誤

133009

雙步驟驗證 PIN 輸入速度太快

輸入雙步驟驗證 PIN 的速度太快。

再試一次之前請先檢查 details 回應值。

400

要求錯誤

133010

這是尚未註冊的電話號碼

尚未在 WhatsApp Business 平台註冊這個電話號碼。

請先註冊電話號碼,再重試一次。

400

要求錯誤

133015

請稍待幾分鐘,再嘗試註冊此電話號碼

您嘗試註冊的電話號碼近期遭到刪除,且刪除程序尚未完成。

請稍待 5 分鐘,再重新嘗試要求。

400

要求錯誤

135000

一般用戶錯誤

要求參數發生不明錯誤,無法傳送訊息。

請參閱端點的參考資料,判斷您用於查詢端點的語法是否正確無誤。若您所收到的回應不斷出現這個錯誤代碼,請聯絡客戶支援團隊

400

要求錯誤