登入開始免費試用
Meta Tech Provider

WhatsApp Cloud API 錯誤代碼

這裡以一個表格列出我們記錄的所有 WhatsApp Cloud API 錯誤代碼,並說明每個代碼的意思及重試是否有用。大部分錯誤都沒有用,因為它們是確定性的。同一個請求會以相同方式失敗,重試迴圈只會把錯誤請求變成速率限制。

EasyCoexistence 持續監察連接,並將 Meta 的帳戶及品質事件記錄在連接時間軸上,因此由號碼狀態引起的錯誤,會在傳送失敗前而非失敗後顯現。

預設不儲存訊息Business 應用程式 + Cloud API供 Claude 及 ChatGPT 使用的 MCP2 分鐘內開始運作

請求

代碼意思重試
100某個參數不受支援、拼寫錯誤或格式錯誤。否
131008完全沒有包含某個必要參數。否
131009參數存在,但其值被端點拒絕。否
131021寄件人與收件人是同一個號碼。否
131051不支援此訊息類型,通常是 Coexistence 的限制。否
131052Meta 無法下載客戶傳送的媒體。否
131053Meta 無法上載您傳送的媒體。原因在於大小、格式或可存取性。否

範本

代碼意思重試
132000參數數量與範本不符。否
132001沒有該名稱與語言組合的範本。否
132007範本違反訊息政策。請改寫後重新提交。否
132012參數格式與範本定義的不一致。否
132015範本因質素下降而被暫停。屬暫時性。等待
132016範本已被永久停用,不會恢復。否

視窗與收件人

代碼意思重試
13104724 小時客戶服務視窗已關閉。請傳送範本。否
131026收件人完全無法接收此訊息。否
131050對方已選擇退出。按設計並無任何變通方法。否
130497您的帳戶被限制向該國家傳送訊息。否

註冊與 PIN

代碼意思重試
131045此號碼從未註冊 Cloud API 訊息功能。否
133010此號碼未註冊。必須完成註冊。否
133006號碼必須先驗證,才能註冊。否
133005雙重驗證 PIN 錯誤。請停止猜測。否
133008PIN 嘗試次數過多。註冊被鎖定一段時間。等待

存取與帳戶

代碼意思重試
190存取權杖已過期或已失效。否
368帳戶因違反政策而受到限制。否
131031帳戶受到限制,或其資料與 Meta 的記錄不符。否
131042企業帳戶的付款問題令訊息無法傳送。否
131049Meta 為保護生態系統健康而攔截了此訊息。否

速率限制

代碼意思重試
130429已達到帳戶的訊息傳輸容量上限。等待
131048觸發了垃圾訊息速率限制。原因是質素,而非數量。否
131056您的號碼與同一收件人之間的訊息過多。否
80007帳戶已達到管理呼叫上限,通常是輪詢所致。等待

暫時性故障

代碼意思重試
131016某項 Meta 服務暫時無法使用。是
131000未分類的失敗。重試一次,然後附上 trace id 上報。是

Coexistence 同步

代碼意思重試
2593107已超過聊天記錄同步上限。否
2593108在 24 小時同步視窗以外嘗試同步。否

如何閱讀重試欄

這一欄有 3 個值,選錯是整份參考資料中代價最高的錯誤。

「否」表示失敗具確定性。出問題的是請求、範本或收件人的狀態;再次傳送完全相同的請求,只會得到相同錯誤,並消耗日後需要的傳輸容量。「是」表示問題出在 Meta 一方,退避重試確實可以解決。「等待」表示條件真實存在,但只是暫時性限制或鎖定,會自行解除。在解除前重試沒有作用,還可能延長限制。

為何大部分錯誤不能重試

因為平台會回傳具體代碼,而不是籠統代碼。參數格式錯誤、不存在的範本、已關閉的訊息視窗,以及已選擇退出的收件人,在回應當刻都可以判定,所以 Meta 會明確指出問題,而不是含糊地讓請求失敗。

  • 請求有問題,第二次嘗試不會令它變正確。
  • 範本有問題,問題存在於範本本身,請求無法改變它。
  • 視窗或選擇退出的問題關乎收件人狀態,而不是您的狀態。
  • 帳戶限制是一項決定,重試並不是申訴。

收到這些代碼時要記錄甚麼

記錄足夠資料,讓您無需重現問題也能診斷。這是 5 分鐘修復與整天猜測之間的分別。

  • 完整錯誤回應,包括追蹤 ID,因為 Meta 支援會要求這項資料。
  • 實際傳送的請求主體,而不是您原本打算傳送的內容。兩者之間的差異通常就是錯誤所在。
  • 號碼 ID,讓您分辨單一號碼的問題與整個帳戶的問題。
  • 時間戳記,讓您可以核對該刻連接的狀態。

只存在於 Coexistence 的代碼

其中有 2 個。它們看起來像普通的傳送失敗,因此容易令人混淆。2593107 和 2593108 都與聊天記錄同步有關,也就是首次連接號碼時,從 WhatsApp Business 應用程式複製最近對話的步驟。

它們不是訊息錯誤,也不代表連接失敗。同步超出限制或在時限外執行時,號碼仍會保持連接並正常傳送,只是複製的記錄少於預期。若將它們理解為連接故障,便可能斷開連接後重新開始,結果只會遺失更多記錄,而不是恢復記錄。

常見問題

哪些錯誤應該重試?

131016 和 131000,配合指數退避。130429、132015 和 133008 在等待後會自行清除。其他錯誤都具確定性。

錯誤代碼是否代表我的號碼已斷開連接?

通常不是。大部分錯誤與請求、範本或收件人有關。連接問題會以帳戶及品質 Webhook 顯示,而不是傳送錯誤。

甚麼是追蹤 ID?

錯誤回應中的識別碼,讓 Meta 支援找出特定請求。每次失敗都應記錄;沒有它,支援工單便無法處理。

這些代碼在每個供應商都相同嗎?

是。它們來自 Meta 的 Cloud API,因此無論由哪個供應商連接號碼,代碼都相同。供應商只能改變錯誤通知您時的清晰程度。

準備開始嗎?

幾分鐘內設定 WhatsApp Coexistence,而非幾個月。應用程式在手機上仍可繼續運作。

開始免費試用3 天內不收取任何費用。隨時取消。

繼續閱讀

參考資料WhatsApp 錯誤 131047:重新互動訊息錯誤 131047 表示該客戶超過 24 小時未再向您發訊息,因此客戶服務時段已關閉,自由格式訊息不會送達。只有 Meta 已批准的訊息範本,才能重新開啟對話。參考資料WhatsApp 錯誤 100:參數無效錯誤 100 表示請求帶有 Meta 不接受的參數:不受支援、拼寫錯誤,或不符合該端點所需的結構。這是可預期的錯誤,因此相同請求每次都會以完全相同的方式失敗,重試也沒有作用。參考資料WhatsApp 錯誤 131016:服務無法使用錯誤 131016 表示 Meta 一方的服務暫時無法使用。這是少數真正屬於暫時性的系統錯誤,因此正確做法是採用指數退避重試,而不是展開調查。參考資料號碼停止運作:如何找出原因當已連接號碼停止運作,原因幾乎從來不是程式碼。請按常見程度依次排查:過期的存取權杖、重新連接後遺失的 Webhook 覆寫、14 天閒置斷開、品質下降,最後是帳戶限制。參考資料WhatsApp Webhook 欄位及其路由位置WhatsApp Business 帳戶會以具名欄位傳送事件。其中 2 個承載對話內容,並路由至您的端點;另外 6 個承載運作狀態,是監察的基礎。了解兩者分別,才能決定架構。指南WhatsApp Coexistence:同一號碼使用應用程式及 APICoexistence 是 Meta 的官方模式,讓 WhatsApp Business 應用程式與 Cloud API 同時使用同一號碼。團隊仍可用電話回覆,保留相同聊天及歷史記錄,同時由軟件在同一條線路上傳送及接收訊息。無需遷移,也無需更換號碼。