參考

錯誤碼參考

結合目前操作讀取 HTTP 狀態、error.code 和 error.numeric_code。細分數字碼可在保留原 HTTP 狀態與 code 時區分原因。error.message 用於診斷，不用於程式分支；保留 request_id。

錯誤回應格式

結合目前操作讀取 HTTP 狀態、error.code 和 error.numeric_code。數字碼以字串處理。保留 request_id 排查；它不是冪等鍵或任務識別碼。

request_id: 必有的字串，由伺服器為本次 HTTP 請求產生，也透過 X-Request-Id 回應標頭傳回；回報問題時提供此值。
client_request_id: 選填字串，僅在請求帶有有效 X-Request-Id 時原樣回傳，用於用戶端核對，不取代伺服器 request_id。
error.code: 為相容性保留的穩定 snake_case 機器可讀碼；請結合操作與 HTTP 狀態解讀。
error.numeric_code: 五位數字字串，可在保留原 code 與 HTTP 狀態時細分原因；它不是全域唯一的操作識別碼。
error.message: 供開發者閱讀的英文診斷文字，可能包含渠道原始原因且用字可變；不要解析或用於程式分支。

錯誤 JSON 示意

{
  "request_id": "req_example",
  "error": {
    "code": "invalid_request",
    "numeric_code": "10000",
    "message": "Invalid request parameters"
  },
  "client_request_id": "<CLIENT_REQUEST_ID>"
}

400 請求錯誤

auth_mode_phone_required20019
此授權方式要求建立帳號時填寫 provider_data.phone。
處理與重試: 按目前操作與渠道條件修正參數後再請求。重複提交相同的無效請求不會解決錯誤。
示意 JSON；message 隨實際原因變化
```
{
  "request_id": "req_example",
  "error": {
    "code": "auth_mode_phone_required",
    "numeric_code": "20019",
    "message": "Phone number is required for this auth mode"
  }
}
```
create_api_key_failed11101
操作被拒絕，請檢查請求並保留 request_id 排查。
處理與重試: 再次建立前先列出或查詢既有資源，確認上次建立是否已生效。修正根本原因並保留 request_id，不要自動建立重複資源。
示意 JSON；message 隨實際原因變化
```
{
  "request_id": "req_example",
  "error": {
    "code": "create_api_key_failed",
    "numeric_code": "11101",
    "message": "Failed to create API key"
  }
}
```
invalid_conversation_type37000
type 必須為 user、group 或 channel。
處理與重試: 按目前操作與渠道條件修正參數後再請求。重複提交相同的無效請求不會解決錯誤。
示意 JSON；message 隨實際原因變化
```
{
  "request_id": "req_example",
  "error": {
    "code": "invalid_conversation_type",
    "numeric_code": "37000",
    "message": "Field 'type' must be one of: user, group, channel"
  }
}
```
invalid_provider30000
檢查 URL 中的管道識別碼。
處理與重試: 按目前操作與渠道條件修正參數後再請求。重複提交相同的無效請求不會解決錯誤。
示意 JSON；message 隨實際原因變化
```
{
  "request_id": "req_example",
  "error": {
    "code": "invalid_provider",
    "numeric_code": "30000",
    "message": "Invalid provider parameter"
  }
}
```
invalid_reply_token36006
無法讀取引用權杖，請原樣複製入站事件的 data.message.reply_token。
處理與重試: 按目前操作與渠道條件修正參數後再請求。重複提交相同的無效請求不會解決錯誤。
示意 JSON；message 隨實際原因變化
```
{
  "request_id": "req_example",
  "error": {
    "code": "invalid_reply_token",
    "numeric_code": "36006",
    "message": "Invalid or unreadable reply_token"
  }
}
```
invalid_request10000
檢查 JSON 請求本文與必填欄位。
處理與重試: 按目前操作與渠道條件修正參數後再請求。重複提交相同的無效請求不會解決錯誤。
示意 JSON；message 隨實際原因變化
```
{
  "request_id": "req_example",
  "error": {
    "code": "invalid_request",
    "numeric_code": "10000",
    "message": "Invalid request parameters"
  }
}
```
invalid_target_workspace11003
工作區覆寫目標為空或格式無效。移除覆寫請求標頭，改用目標工作區所屬的 API Key。
處理與重試: 按目前操作與渠道條件修正參數後再請求。重複提交相同的無效請求不會解決錯誤。
示意 JSON；message 隨實際原因變化
```
{
  "request_id": "req_example",
  "error": {
    "code": "invalid_target_workspace",
    "numeric_code": "11003",
    "message": "Invalid target workspace"
  }
}
```
provider_invalid_request30001
檢查管道專屬欄位及格式。
處理與重試: 按目前操作與渠道條件修正參數後再請求。重複提交相同的無效請求不會解決錯誤。
示意 JSON；message 隨實際原因變化
```
{
  "request_id": "req_example",
  "error": {
    "code": "provider_invalid_request",
    "numeric_code": "30001",
    "message": "Provider rejected the request"
  }
}
```
rotate_api_key_failed11103
操作被拒絕，請檢查請求並保留 request_id 排查。
處理與重試: 修改或輪替前核對目前工作區下的目標 Key。目標不存在不會因重試修復。輪替結果未知時，安全確認哪些憑證仍可用，不暴露金鑰內容。
示意 JSON；message 隨實際原因變化
```
{
  "request_id": "req_example",
  "error": {
    "code": "rotate_api_key_failed",
    "numeric_code": "11103",
    "message": "Failed to rotate API key"
  }
}
```
unsupported_action30005
無法識別此帳號操作，請使用文件列出的操作。
處理與重試: 選擇文件列為支援的渠道與動作。重複請求不會增加能力或開通內測權限。
示意 JSON；message 隨實際原因變化
```
{
  "request_id": "req_example",
  "error": {
    "code": "unsupported_action",
    "numeric_code": "30005",
    "message": "Action not supported"
  }
}
```
unsupported_conversation_type37001
管道不支援此操作，請選擇能力表中支援的操作。
處理與重試: 選擇文件列為支援的渠道與動作。重複請求不會增加能力或開通內測權限。
示意 JSON；message 隨實際原因變化
```
{
  "request_id": "req_example",
  "error": {
    "code": "unsupported_conversation_type",
    "numeric_code": "37001",
    "message": "Operation not supported for this conversation type"
  }
}
```
unsupported_message_type36000
請使用此管道支援的 message.type。
處理與重試: 選擇文件列為支援的渠道與動作。重複請求不會增加能力或開通內測權限。
示意 JSON；message 隨實際原因變化
```
{
  "request_id": "req_example",
  "error": {
    "code": "unsupported_message_type",
    "numeric_code": "36000",
    "message": "Message type not supported"
  }
}
```
unsupported_provider_auth_mode20018
請使用此管道支援的 auth_mode。
處理與重試: 選擇文件列為支援的渠道與動作。重複請求不會增加能力或開通內測權限。
示意 JSON；message 隨實際原因變化
```
{
  "request_id": "req_example",
  "error": {
    "code": "unsupported_provider_auth_mode",
    "numeric_code": "20018",
    "message": "Auth mode not supported by this provider"
  }
}
```
update_api_key_failed11102
操作被拒絕，請檢查請求並保留 request_id 排查。
處理與重試: 修改或輪替前核對目前工作區下的目標 Key。目標不存在不會因重試修復。輪替結果未知時，安全確認哪些憑證仍可用，不暴露金鑰內容。
示意 JSON；message 隨實際原因變化
```
{
  "request_id": "req_example",
  "error": {
    "code": "update_api_key_failed",
    "numeric_code": "11102",
    "message": "Failed to update API key"
  }
}
```
update_workspace_failed41001
操作被拒絕，請檢查請求並保留 request_id 排查。
處理與重試: 先讀取資源目前狀態，確認上一次變更結果，再決定是否重試。保留 request_id；結果未知時不要自動重複寫入。
示意 JSON；message 隨實際原因變化
```
{
  "request_id": "req_example",
  "error": {
    "code": "update_workspace_failed",
    "numeric_code": "41001",
    "message": "Failed to update workspace"
  }
}
```
wallet_invalid_request20021
請檢查餘額建號參數及可選的 Idempotency-Key 請求標頭。
處理與重試: 按目前操作與渠道條件修正參數後再請求。重複提交相同的無效請求不會解決錯誤。
示意 JSON；message 隨實際原因變化
```
{
  "request_id": "req_example",
  "error": {
    "code": "wallet_invalid_request",
    "numeric_code": "20021",
    "message": "Invalid wallet account request"
  }
}
```

401 未授權

invalid_api_key11001
檢查 API Key 是否正確且已啟用。
處理與重試: 保留 request_id 與結構化錯誤碼，先排查目前操作，再決定下一步。
示意 JSON；message 隨實際原因變化
```
{
  "request_id": "req_example",
  "error": {
    "code": "invalid_api_key",
    "numeric_code": "11001",
    "message": "Invalid API key"
  }
}
```
missing_api_key11000
請加入 X-Api-Key 請求標頭。
處理與重試: 保留 request_id 與結構化錯誤碼，先排查目前操作，再決定下一步。
示意 JSON；message 隨實際原因變化
```
{
  "request_id": "req_example",
  "error": {
    "code": "missing_api_key",
    "numeric_code": "11000",
    "message": "Missing X-Api-Key header"
  }
}
```

403 禁止存取

beta_feature_not_enabled41002
工作區需開通內測資格，才能使用通話介面及明確訂閱通話事件。
處理與重試: 保留 request_id 與結構化錯誤碼，先排查目前操作，再決定下一步。
示意 JSON；message 隨實際原因變化
```
{
  "request_id": "req_example",
  "error": {
    "code": "beta_feature_not_enabled",
    "numeric_code": "41002",
    "message": "Beta feature not enabled"
  }
}
```
cors_forbidden11009
CORS 來源、方法或請求標頭不被允許，請檢查呼叫環境。
處理與重試: 保留 request_id 與結構化錯誤碼，先排查目前操作，再決定下一步。
示意 JSON；message 隨實際原因變化
```
{
  "request_id": "req_example",
  "error": {
    "code": "cors_forbidden",
    "numeric_code": "11009",
    "message": "CORS preflight request is not allowed"
  }
}
```
post_inaccessible39005
貼文與留言
核對帳號及本介面實際要求的目標識別碼。post_not_found 表示已確認貼文不存在；comment_not_found 僅表示驗證後未找到目標第一層留言，不代表已搜尋全部回覆。post_inaccessible 表示無法存取，不證明不存在，也不指明原因。保留錯誤，查明後再選擇下一步。
處理與重試: 核對目標識別碼、資源歸屬與目前工作區。不要將已確認缺失或無法存取的目標當作暫時服務故障自動重試。
示意 JSON；message 隨實際原因變化
```
{
  "request_id": "req_example",
  "error": {
    "code": "post_inaccessible",
    "numeric_code": "39005",
    "message": "Post is not accessible"
  }
}
```
workspace_override_forbidden11002
請求嘗試使用此 API Key 無權使用的工作區覆寫。移除覆寫請求標頭，改用目標工作區所屬的 API Key。
處理與重試: 保留 request_id 與結構化錯誤碼，先排查目前操作，再決定下一步。
示意 JSON；message 隨實際原因變化
```
{
  "request_id": "req_example",
  "error": {
    "code": "workspace_override_forbidden",
    "numeric_code": "11002",
    "message": "Workspace override is not allowed"
  }
}
```

404 找不到資源

account_not_found20020
核對 account_id，並使用帳號所屬工作區的 X-Api-Key。此工作區下未找到的帳號無法使用目前 Key 存取。
處理與重試: 核對目標識別碼、資源歸屬與目前工作區。不要將已確認缺失或無法存取的目標當作暫時服務故障自動重試。
示意 JSON；message 隨實際原因變化
```
{
  "request_id": "req_example",
  "error": {
    "code": "account_not_found",
    "numeric_code": "20020",
    "message": "Account not found"
  }
}
```
account_operation_not_found20029
操作不存在或不屬於目前工作區，請核對原 operation_id 與 API Key 範圍。
處理與重試: 核對目標識別碼、資源歸屬與目前工作區。不要將已確認缺失或無法存取的目標當作暫時服務故障自動重試。
示意 JSON；message 隨實際原因變化
```
{
  "request_id": "req_example",
  "error": {
    "code": "account_operation_not_found",
    "numeric_code": "20029",
    "message": "Account operation not found"
  }
}
```
call_not_found38003
通話
目前帳號與工作區下不存在該通話。
處理與重試: 核對目標識別碼、資源歸屬與目前工作區。不要將已確認缺失或無法存取的目標當作暫時服務故障自動重試。
示意 JSON；message 隨實際原因變化
```
{
  "request_id": "req_example",
  "error": {
    "code": "call_not_found",
    "numeric_code": "38003",
    "message": "Call not found"
  }
}
```
comment_not_found39001
貼文與留言
核對帳號及本介面實際要求的目標識別碼。post_not_found 表示已確認貼文不存在；comment_not_found 僅表示驗證後未找到目標第一層留言，不代表已搜尋全部回覆。post_inaccessible 表示無法存取，不證明不存在，也不指明原因。保留錯誤，查明後再選擇下一步。
處理與重試: 核對目標識別碼、資源歸屬與目前工作區。不要將已確認缺失或無法存取的目標當作暫時服務故障自動重試。
示意 JSON；message 隨實際原因變化
```
{
  "request_id": "req_example",
  "error": {
    "code": "comment_not_found",
    "numeric_code": "39001",
    "message": "Comment not found"
  }
}
```
contact_not_found35000
此帳號下未找到聯絡人，請核對識別碼。
處理與重試: 核對目標識別碼、資源歸屬與目前工作區。不要將已確認缺失或無法存取的目標當作暫時服務故障自動重試。
示意 JSON；message 隨實際原因變化
```
{
  "request_id": "req_example",
  "error": {
    "code": "contact_not_found",
    "numeric_code": "35000",
    "message": "Contact not found"
  }
}
```
conversation_not_found37002
管道未找到此對話，請核對識別碼與所屬帳號。
處理與重試: 核對目標識別碼、資源歸屬與目前工作區。不要將已確認缺失或無法存取的目標當作暫時服務故障自動重試。
示意 JSON；message 隨實際原因變化
```
{
  "request_id": "req_example",
  "error": {
    "code": "conversation_not_found",
    "numeric_code": "37002",
    "message": "Conversation not found"
  }
}
```
group_not_found34004
此帳號下未找到群組，請核對群組 ID。
處理與重試: 核對目標識別碼、資源歸屬與目前工作區。不要將已確認缺失或無法存取的目標當作暫時服務故障自動重試。
示意 JSON；message 隨實際原因變化
```
{
  "request_id": "req_example",
  "error": {
    "code": "group_not_found",
    "numeric_code": "34004",
    "message": "Group not found"
  }
}
```
not_found10001
請檢查 API 路徑與 HTTP 方法。
處理與重試: 核對目標識別碼、資源歸屬與目前工作區。不要將已確認缺失或無法存取的目標當作暫時服務故障自動重試。
示意 JSON；message 隨實際原因變化
```
{
  "request_id": "req_example",
  "error": {
    "code": "not_found",
    "numeric_code": "10001",
    "message": "Endpoint not found"
  }
}
```
post_not_found39000
貼文與留言
核對帳號及本介面實際要求的目標識別碼。post_not_found 表示已確認貼文不存在；comment_not_found 僅表示驗證後未找到目標第一層留言，不代表已搜尋全部回覆。post_inaccessible 表示無法存取，不證明不存在，也不指明原因。保留錯誤，查明後再選擇下一步。
處理與重試: 核對目標識別碼、資源歸屬與目前工作區。不要將已確認缺失或無法存取的目標當作暫時服務故障自動重試。
示意 JSON；message 隨實際原因變化
```
{
  "request_id": "req_example",
  "error": {
    "code": "post_not_found",
    "numeric_code": "39000",
    "message": "Post not found"
  }
}
```
target_workspace_not_found11004
覆寫指定的工作區不存在或不可用。核對工作區歸屬，移除覆寫請求標頭並使用目標工作區 API Key；重複請求不會增加存取權限。
處理與重試: 核對目標識別碼、資源歸屬與目前工作區。不要將已確認缺失或無法存取的目標當作暫時服務故障自動重試。
示意 JSON；message 隨實際原因變化
```
{
  "request_id": "req_example",
  "error": {
    "code": "target_workspace_not_found",
    "numeric_code": "11004",
    "message": "Target workspace not found"
  }
}
```

409 衝突

account_allocation_busy20011

帳號正在分配，請稍後重試。

處理與重試: 保留 request_id 與結構化錯誤碼，先排查目前操作，再決定下一步。

示意 JSON；message 隨實際原因變化

{
  "request_id": "req_example",
  "error": {
    "code": "account_allocation_busy",
    "numeric_code": "20011",
    "message": "Allocation is busy in the current region; please retry later"
  }
}

account_already_authorized20016
帳號已完成授權，本次動作拒絕重複授權。重新整理授權狀態並沿用已完成結果，不要循環重新授權或取消。
處理與重試: 保留 request_id 與結構化錯誤碼，先排查目前操作，再決定下一步。
示意 JSON；message 隨實際原因變化
```
{
  "request_id": "req_example",
  "error": {
    "code": "account_already_authorized",
    "numeric_code": "20016",
    "message": "Account is already authorized; re-authentication is not required"
  }
}
```
account_binding_not_found30006
帳號尚無有效的管道連線綁定，請檢查帳號狀態。
處理與重試: 查詢授權與執行狀態，再按目標狀態和渠道支援選擇重新整理、啟動或重新連線。連線問題本身不證明已登出；執行依賴連線的業務操作前確認 running。
示意 JSON；message 隨實際原因變化
```
{
  "request_id": "req_example",
  "error": {
    "code": "account_binding_not_found",
    "numeric_code": "30006",
    "message": "Account is not bound to an available server"
  }
}
```
account_webhook_already_exists40008
Webhook 端點
使用 account_id 列出此帳號的獨立端點，更新既有 active 端點。需要切換時，先停用舊 active 端點，再啟用其他端點；不要自動重試建立或重新啟用。
處理與重試: 重新提交前先讀取端點設定與帳號歸屬。PATCH 會取代設定，保留所需訂閱、簽章設定與重試策略。active 名額衝突時更新既有端點，或先停用舊端點再啟用其他端點。
示意 JSON；message 隨實際原因變化
```
{
  "request_id": "req_example",
  "error": {
    "code": "account_webhook_already_exists",
    "numeric_code": "40008",
    "message": "Account already has an active webhook endpoint"
  }
}
```
billing_quote_changed20027
工作區價格或計價依據已變更，請先確認原結果，再取得新報價。
處理與重試: 保留 request_id 與結構化錯誤碼，先排查目前操作，再決定下一步。
示意 JSON；message 隨實際原因變化
```
{
  "request_id": "req_example",
  "error": {
    "code": "billing_quote_changed",
    "numeric_code": "20027",
    "message": "Pricing changed; request a new quote"
  }
}
```
billing_quote_expired20026
報價已過期，請先確認先前建號結果，再取得新報價。
處理與重試: 保留 request_id 與結構化錯誤碼，先排查目前操作，再決定下一步。
示意 JSON；message 隨實際原因變化
```
{
  "request_id": "req_example",
  "error": {
    "code": "billing_quote_expired",
    "numeric_code": "20026",
    "message": "Billing quote expired"
  }
}
```
billing_quote_invalid20025
報價與工作區或請求不符，請先確認原結果，再用相同參數重新報價。
處理與重試: 保留 request_id 與結構化錯誤碼，先排查目前操作，再決定下一步。
示意 JSON；message 隨實際原因變化
```
{
  "request_id": "req_example",
  "error": {
    "code": "billing_quote_invalid",
    "numeric_code": "20025",
    "message": "Billing quote does not match this request"
  }
}
```
call_already_active38000
通話
帳號已有受管理的活躍通話。核對已知通話與本次動作意圖；此錯誤本身不要求掛斷，也不要求反覆呼叫同一個失敗查詢。
處理與重試: 保留 request_id 與結構化錯誤碼，先排查目前操作，再決定下一步。
示意 JSON；message 隨實際原因變化
```
{
  "request_id": "req_example",
  "error": {
    "code": "call_already_active",
    "numeric_code": "38000",
    "message": "Account already has an active call"
  }
}
```

duplicate_provider_account20015

工作區內已有另一個帳號綁定相同管道身分。

處理與重試: 保留 request_id 與結構化錯誤碼，先排查目前操作，再決定下一步。

示意 JSON；message 隨實際原因變化

{
  "request_id": "req_example",
  "error": {
    "code": "duplicate_provider_account",
    "numeric_code": "20015",
    "message": "A provider account with the same identity already exists in this workspace"
  }
}

no_allocatable_server20013
此區域暫無可分配資源，請查詢其他可分配區域。
處理與重試: 保留 request_id 與結構化錯誤碼，先排查目前操作，再決定下一步。
示意 JSON；message 隨實際原因變化
```
{
  "request_id": "req_example",
  "error": {
    "code": "no_allocatable_server",
    "numeric_code": "20013",
    "message": "No allocatable server in the current region"
  }
}
```

provider_account_mismatch20017

請求中的管道身分與帳號綁定不一致。

處理與重試: 保留 request_id 與結構化錯誤碼，先排查目前操作，再決定下一步。

示意 JSON；message 隨實際原因變化

{
  "request_id": "req_example",
  "error": {
    "code": "provider_account_mismatch",
    "numeric_code": "20017",
    "message": "Authenticated provider account does not match the bound account; re-scan with the original account"
  }
}

provider_not_ready30009
連線尚未就緒，請檢查授權及 runtime_status 後再決定是否重試。
處理與重試: 查詢授權與執行狀態，再按目標狀態和渠道支援選擇重新整理、啟動或重新連線。連線問題本身不證明已登出；執行依賴連線的業務操作前確認 running。
示意 JSON；message 隨實際原因變化
```
{
  "request_id": "req_example",
  "error": {
    "code": "provider_not_ready",
    "numeric_code": "30009",
    "message": "Provider client is not ready"
  }
}
```
wallet_account_creation_in_progress20030
目前工作區已有餘額帳號正在建立，請等待完成後再試。
處理與重試: 保留 request_id 與結構化錯誤碼，先排查目前操作，再決定下一步。
示意 JSON；message 隨實際原因變化
```
{
  "request_id": "req_example",
  "error": {
    "code": "wallet_account_creation_in_progress",
    "numeric_code": "20030",
    "message": "Account creation is in progress; please wait"
  }
}
```
wallet_idempotency_conflict20024
冪等鍵已綁定其他業務參數，請先核對原操作結果，避免重複建號。
處理與重試: 保留 request_id 與結構化錯誤碼，先排查目前操作，再決定下一步。
示意 JSON；message 隨實際原因變化
```
{
  "request_id": "req_example",
  "error": {
    "code": "wallet_idempotency_conflict",
    "numeric_code": "20024",
    "message": "Idempotency key was used for a different request"
  }
}
```
wallet_insufficient_funds20023
錢包餘額不足，擁有者可儲值後確認原請求。
處理與重試: 保留 request_id 與結構化錯誤碼，先排查目前操作，再決定下一步。
示意 JSON；message 隨實際原因變化
```
{
  "request_id": "req_example",
  "error": {
    "code": "wallet_insufficient_funds",
    "numeric_code": "20023",
    "message": "Insufficient wallet balance"
  }
}
```
wallet_workspace_disabled20022
新餘額消費已關閉，不代表既有帳號操作已取消。
處理與重試: 保留 request_id 與結構化錯誤碼，先排查目前操作，再決定下一步。
示意 JSON；message 隨實際原因變化
```
{
  "request_id": "req_example",
  "error": {
    "code": "wallet_workspace_disabled",
    "numeric_code": "20022",
    "message": "New wallet purchases are disabled"
  }
}
```
workspace_account_quota_exceeded20014
工作區訊息帳號額度已用滿，請檢查用量與額度。
處理與重試: 保留 request_id 與結構化錯誤碼，先排查目前操作，再決定下一步。
示意 JSON；message 隨實際原因變化
```
{
  "request_id": "req_example",
  "error": {
    "code": "workspace_account_quota_exceeded",
    "numeric_code": "20014",
    "message": "Workspace account quota exceeded"
  }
}
```

422 無法處理的實體

contact_not_found35000
GET /contacts/info 回傳 Conversation not found，請核對目標識別碼與本次查詢使用的帳號。
處理與重試: 核對目標識別碼、資源歸屬與目前工作區。不要將已確認缺失或無法存取的目標當作暫時服務故障自動重試。
示意 JSON；message 隨實際原因變化
```
{
  "request_id": "req_example",
  "error": {
    "code": "contact_not_found",
    "numeric_code": "35000",
    "message": "Conversation not found"
  }
}
```

500 伺服器錯誤

block_contact_failed35005
封鎖聯絡人：未分類錯誤中斷本次變更，需確認資源最終狀態。
處理與重試: 先讀取資源目前狀態，確認上一次變更結果，再決定是否重試。保留 request_id；結果未知時不要自動重複寫入。
示意 JSON；message 隨實際原因變化
```
{
  "request_id": "req_example",
  "error": {
    "code": "block_contact_failed",
    "numeric_code": "35005",
    "message": "Failed to block contact"
  }
}
```
call_control_failed38004
通話
未能查詢或結束通話；依本次動作核對通話狀態。
處理與重試: 建立或結束通話前，查詢目前受管理通話及 call_id/state。preparing 不表示撥號或接通；ended 與 failed 都是終態，不要僅因 failed 重複掛斷。
示意 JSON；message 隨實際原因變化
```
{
  "request_id": "req_example",
  "error": {
    "code": "call_control_failed",
    "numeric_code": "38004",
    "message": "Failed to control call"
  }
}
```
create_account_failed20002
建立帳號：資源建立失敗或無法確認建立結果。
處理與重試: 再次建立前先列出或查詢既有資源，確認上次建立是否已生效。修正根本原因並保留 request_id，不要自動建立重複資源。
示意 JSON；message 隨實際原因變化
```
{
  "request_id": "req_example",
  "error": {
    "code": "create_account_failed",
    "numeric_code": "20002",
    "message": "Failed to create account"
  }
}
```
create_call_failed38002
通話
建立通話：資源建立失敗或無法確認建立結果。
處理與重試: 再次建立前先列出或查詢既有資源，確認上次建立是否已生效。修正根本原因並保留 request_id，不要自動建立重複資源。
示意 JSON；message 隨實際原因變化
```
{
  "request_id": "req_example",
  "error": {
    "code": "create_call_failed",
    "numeric_code": "38002",
    "message": "Failed to create call"
  }
}
```
create_contact_failed35003
新增聯絡人：資源建立失敗或無法確認建立結果。
處理與重試: 再次建立前先列出或查詢既有資源，確認上次建立是否已生效。修正根本原因並保留 request_id，不要自動建立重複資源。
示意 JSON；message 隨實際原因變化
```
{
  "request_id": "req_example",
  "error": {
    "code": "create_contact_failed",
    "numeric_code": "35003",
    "message": "Failed to create contact"
  }
}
```
create_group_failed34002
建立群組：資源建立失敗或無法確認建立結果。
處理與重試: 再次建立前先列出或查詢既有資源，確認上次建立是否已生效。修正根本原因並保留 request_id，不要自動建立重複資源。
示意 JSON；message 隨實際原因變化
```
{
  "request_id": "req_example",
  "error": {
    "code": "create_group_failed",
    "numeric_code": "34002",
    "message": "Failed to create group"
  }
}
```
create_webhook_endpoint_failed40001
建立 Webhook 端點：未分類錯誤中斷本次變更，需確認資源最終狀態。
處理與重試: 重新提交前先讀取端點設定與帳號歸屬。PATCH 會取代設定，保留所需訂閱、簽章設定與重試策略。active 名額衝突時更新既有端點，或先停用舊端點再啟用其他端點。
示意 JSON；message 隨實際原因變化
```
{
  "request_id": "req_example",
  "error": {
    "code": "create_webhook_endpoint_failed",
    "numeric_code": "40001",
    "message": "Failed to create webhook endpoint"
  }
}
```
deactivate_webhook_endpoint_failed40004
停用 Webhook 端點：無法確認停止或停用結果，恢復時應保留原本停止目標。
處理與重試: 查詢目前狀態，確認停止或停用是否已生效。不要為了恢復本次操作而啟動或重新連線原本要停止的資源。
示意 JSON；message 隨實際原因變化
```
{
  "request_id": "req_example",
  "error": {
    "code": "deactivate_webhook_endpoint_failed",
    "numeric_code": "40004",
    "message": "Failed to deactivate webhook endpoint"
  }
}
```
delete_account_failed20004
刪除帳號：無法確認本次刪除結果。
處理與重試: 查詢資源確認是否已刪除，再決定是否需要再次刪除。保留 request_id，按目前介面宣告的成功回應處理。
示意 JSON；message 隨實際原因變化
```
{
  "request_id": "req_example",
  "error": {
    "code": "delete_account_failed",
    "numeric_code": "20004",
    "message": "Failed to delete account"
  }
}
```
delete_label_failed37014
刪除標籤：無法確認本次刪除結果。
處理與重試: 查詢資源確認是否已刪除，再決定是否需要再次刪除。保留 request_id，按目前介面宣告的成功回應處理。
示意 JSON；message 隨實際原因變化
```
{
  "request_id": "req_example",
  "error": {
    "code": "delete_label_failed",
    "numeric_code": "37014",
    "message": "Failed to delete label"
  }
}
```
delete_webhook_endpoint_failed40005
刪除 Webhook 端點：無法確認本次刪除結果。
處理與重試: 查詢資源確認是否已刪除，再決定是否需要再次刪除。保留 request_id，按目前介面宣告的成功回應處理。
示意 JSON；message 隨實際原因變化
```
{
  "request_id": "req_example",
  "error": {
    "code": "delete_webhook_endpoint_failed",
    "numeric_code": "40005",
    "message": "Failed to delete webhook endpoint"
  }
}
```
edit_message_failed36005
編輯訊息：未分類錯誤中斷本次變更，需確認資源最終狀態。
處理與重試: 先讀取資源目前狀態，確認上一次變更結果，再決定是否重試。保留 request_id；結果未知時不要自動重複寫入。
示意 JSON；message 隨實際原因變化
```
{
  "request_id": "req_example",
  "error": {
    "code": "edit_message_failed",
    "numeric_code": "36005",
    "message": "Failed to edit message"
  }
}
```
get_account_failed20001
取得帳號：服務未能產生有效的查詢結果。
處理與重試: 保留 request_id，核對目標識別碼與帳號存取範圍。查明原因後再重試查詢；查詢失敗不等於結果為空或資源不存在。
示意 JSON；message 隨實際原因變化
```
{
  "request_id": "req_example",
  "error": {
    "code": "get_account_failed",
    "numeric_code": "20001",
    "message": "Failed to get account"
  }
}
```
get_auth_state_failed20006
取得認證狀態：服務未能產生有效的查詢結果。
處理與重試: 保留 request_id，核對目標識別碼與帳號存取範圍。查明原因後再重試查詢；查詢失敗不等於結果為空或資源不存在。
示意 JSON；message 隨實際原因變化
```
{
  "request_id": "req_example",
  "error": {
    "code": "get_auth_state_failed",
    "numeric_code": "20006",
    "message": "Failed to get account auth state"
  }
}
```
get_contact_failed35002
取得聯絡人詳情：服務未能產生有效的查詢結果。
處理與重試: 保留 request_id，核對目標識別碼與帳號存取範圍。查明原因後再重試查詢；查詢失敗不等於結果為空或資源不存在。
示意 JSON；message 隨實際原因變化
```
{
  "request_id": "req_example",
  "error": {
    "code": "get_contact_failed",
    "numeric_code": "35002",
    "message": "Failed to get contact"
  }
}
```
get_contact_membership_failed35004
查詢聯絡人狀態：服務未能產生有效的查詢結果。
處理與重試: 保留 request_id，核對目標識別碼與帳號存取範圍。查明原因後再重試查詢；查詢失敗不等於結果為空或資源不存在。
示意 JSON；message 隨實際原因變化
```
{
  "request_id": "req_example",
  "error": {
    "code": "get_contact_membership_failed",
    "numeric_code": "35004",
    "message": "Failed to get contact membership"
  }
}
```
get_conversation_failed37004
取得會話詳情：服務未能產生有效的查詢結果。
處理與重試: 保留 request_id，核對目標識別碼與帳號存取範圍。查明原因後再重試查詢；查詢失敗不等於結果為空或資源不存在。
示意 JSON；message 隨實際原因變化
```
{
  "request_id": "req_example",
  "error": {
    "code": "get_conversation_failed",
    "numeric_code": "37004",
    "message": "Failed to get conversation"
  }
}
```
get_group_failed34001
查詢群組詳情：服務未能產生有效的查詢結果。
處理與重試: 保留 request_id，核對目標識別碼與帳號存取範圍。查明原因後再重試查詢；查詢失敗不等於結果為空或資源不存在。
示意 JSON；message 隨實際原因變化
```
{
  "request_id": "req_example",
  "error": {
    "code": "get_group_failed",
    "numeric_code": "34001",
    "message": "Failed to get group"
  }
}
```
get_group_invite_code_failed34010
取得群組邀請連結：服務未能產生有效的查詢結果。
處理與重試: 保留 request_id，核對目標識別碼與帳號存取範圍。查明原因後再重試查詢；查詢失敗不等於結果為空或資源不存在。
示意 JSON；message 隨實際原因變化
```
{
  "request_id": "req_example",
  "error": {
    "code": "get_group_invite_code_failed",
    "numeric_code": "34010",
    "message": "Failed to get group invite code"
  }
}
```
get_session_failed20005
查詢目前帳號工作階段：服務未能讀取目前工作階段。
處理與重試: 保留 request_id，核對目標識別碼與帳號存取範圍。查明原因後再重試查詢；查詢失敗不等於結果為空或資源不存在。
示意 JSON；message 隨實際原因變化
```
{
  "request_id": "req_example",
  "error": {
    "code": "get_session_failed",
    "numeric_code": "20005",
    "message": "Failed to get account session"
  }
}
```
get_webhook_endpoint_failed40002
取得 Webhook 端點：服務未能產生有效的查詢結果。
處理與重試: 保留 request_id，核對目標識別碼與帳號存取範圍。查明原因後再重試查詢；查詢失敗不等於結果為空或資源不存在。
示意 JSON；message 隨實際原因變化
```
{
  "request_id": "req_example",
  "error": {
    "code": "get_webhook_endpoint_failed",
    "numeric_code": "40002",
    "message": "Failed to get webhook endpoint"
  }
}
```
get_workspace_failed41000
取得目前工作區：服務未能產生有效的查詢結果。
處理與重試: 保留 request_id，核對目標識別碼與帳號存取範圍。查明原因後再重試查詢；查詢失敗不等於結果為空或資源不存在。
示意 JSON；message 隨實際原因變化
```
{
  "request_id": "req_example",
  "error": {
    "code": "get_workspace_failed",
    "numeric_code": "41000",
    "message": "Failed to get workspace"
  }
}
```
leave_group_failed34003
退出群組：未分類錯誤中斷本次變更，需確認資源最終狀態。
處理與重試: 先讀取資源目前狀態，確認上一次變更結果，再決定是否重試。保留 request_id；結果未知時不要自動重複寫入。
示意 JSON；message 隨實際原因變化
```
{
  "request_id": "req_example",
  "error": {
    "code": "leave_group_failed",
    "numeric_code": "34003",
    "message": "Failed to leave group"
  }
}
```
list_accounts_failed20000
列出帳號：服務未能產生有效的查詢結果。
處理與重試: 保留 request_id，核對目標識別碼與帳號存取範圍。查明原因後再重試查詢；查詢失敗不等於結果為空或資源不存在。
示意 JSON；message 隨實際原因變化
```
{
  "request_id": "req_example",
  "error": {
    "code": "list_accounts_failed",
    "numeric_code": "20000",
    "message": "Failed to list accounts"
  }
}
```
list_api_keys_failed11100
列出 API Key：服務未能產生有效的查詢結果。
處理與重試: 保留 request_id，核對目標識別碼與帳號存取範圍。查明原因後再重試查詢；查詢失敗不等於結果為空或資源不存在。
示意 JSON；message 隨實際原因變化
```
{
  "request_id": "req_example",
  "error": {
    "code": "list_api_keys_failed",
    "numeric_code": "11100",
    "message": "Failed to list API keys"
  }
}
```
list_blocklist_failed35007
取得黑名單：服務未能產生有效的查詢結果。
處理與重試: 保留 request_id，核對目標識別碼與帳號存取範圍。查明原因後再重試查詢；查詢失敗不等於結果為空或資源不存在。
示意 JSON；message 隨實際原因變化
```
{
  "request_id": "req_example",
  "error": {
    "code": "list_blocklist_failed",
    "numeric_code": "35007",
    "message": "Failed to list blocklist"
  }
}
```
list_contacts_failed35001
列出聯絡人：服務未能產生有效的查詢結果。
處理與重試: 保留 request_id，核對目標識別碼與帳號存取範圍。查明原因後再重試查詢；查詢失敗不等於結果為空或資源不存在。
示意 JSON；message 隨實際原因變化
```
{
  "request_id": "req_example",
  "error": {
    "code": "list_contacts_failed",
    "numeric_code": "35001",
    "message": "Failed to list contacts"
  }
}
```
list_conversation_labels_failed37012
列出會話標籤：服務未能產生有效的查詢結果。
處理與重試: 保留 request_id，核對目標識別碼與帳號存取範圍。查明原因後再重試查詢；查詢失敗不等於結果為空或資源不存在。
示意 JSON；message 隨實際原因變化
```
{
  "request_id": "req_example",
  "error": {
    "code": "list_conversation_labels_failed",
    "numeric_code": "37012",
    "message": "Failed to list conversation labels"
  }
}
```
list_conversation_members_failed37005
列出會話成員：服務未能產生有效的查詢結果。
處理與重試: 保留 request_id，核對目標識別碼與帳號存取範圍。查明原因後再重試查詢；查詢失敗不等於結果為空或資源不存在。
示意 JSON；message 隨實際原因變化
```
{
  "request_id": "req_example",
  "error": {
    "code": "list_conversation_members_failed",
    "numeric_code": "37005",
    "message": "Failed to list conversation members"
  }
}
```
list_conversations_failed37003
列出會話：服務未能產生有效的查詢結果。
處理與重試: 保留 request_id，核對目標識別碼與帳號存取範圍。查明原因後再重試查詢；查詢失敗不等於結果為空或資源不存在。
示意 JSON；message 隨實際原因變化
```
{
  "request_id": "req_example",
  "error": {
    "code": "list_conversations_failed",
    "numeric_code": "37003",
    "message": "Failed to list conversations"
  }
}
```
list_group_join_requests_failed34007
列出入群申請：服務未能產生有效的查詢結果。
處理與重試: 保留 request_id，核對目標識別碼與帳號存取範圍。查明原因後再重試查詢；查詢失敗不等於結果為空或資源不存在。
示意 JSON；message 隨實際原因變化
```
{
  "request_id": "req_example",
  "error": {
    "code": "list_group_join_requests_failed",
    "numeric_code": "34007",
    "message": "Failed to list group join requests"
  }
}
```
list_groups_failed34000
列出群組：服務未能產生有效的查詢結果。
處理與重試: 保留 request_id，核對目標識別碼與帳號存取範圍。查明原因後再重試查詢；查詢失敗不等於結果為空或資源不存在。
示意 JSON；message 隨實際原因變化
```
{
  "request_id": "req_example",
  "error": {
    "code": "list_groups_failed",
    "numeric_code": "34000",
    "message": "Failed to list groups"
  }
}
```
list_provider_regions_failed30011
列出渠道區域：服務未能產生有效的查詢結果。
處理與重試: 保留 request_id，核對目標識別碼與帳號存取範圍。查明原因後再重試查詢；查詢失敗不等於結果為空或資源不存在。
示意 JSON；message 隨實際原因變化
```
{
  "request_id": "req_example",
  "error": {
    "code": "list_provider_regions_failed",
    "numeric_code": "30011",
    "message": "Failed to list provider regions"
  }
}
```
list_webhook_endpoints_failed40000
列出 Webhook 端點：服務未能產生有效的查詢結果。
處理與重試: 保留 request_id，核對目標識別碼與帳號存取範圍。查明原因後再重試查詢；查詢失敗不等於結果為空或資源不存在。
示意 JSON；message 隨實際原因變化
```
{
  "request_id": "req_example",
  "error": {
    "code": "list_webhook_endpoints_failed",
    "numeric_code": "40000",
    "message": "Failed to list webhook endpoints"
  }
}
```
mark_conversation_read_failed37006
將對話標記為已讀：未分類錯誤中斷本次變更，需確認資源最終狀態。
處理與重試: 先讀取資源目前狀態，確認上一次變更結果，再決定是否重試。保留 request_id；結果未知時不要自動重複寫入。
示意 JSON；message 隨實際原因變化
```
{
  "request_id": "req_example",
  "error": {
    "code": "mark_conversation_read_failed",
    "numeric_code": "37006",
    "message": "Failed to mark conversation as read"
  }
}
```
mark_conversation_unread_failed37007
將對話標記為未讀：未分類錯誤中斷本次變更，需確認資源最終狀態。
處理與重試: 先讀取資源目前狀態，確認上一次變更結果，再決定是否重試。保留 request_id；結果未知時不要自動重複寫入。
示意 JSON；message 隨實際原因變化
```
{
  "request_id": "req_example",
  "error": {
    "code": "mark_conversation_unread_failed",
    "numeric_code": "37007",
    "message": "Failed to mark conversation as unread"
  }
}
```
mute_conversation_failed37008
關閉對話通知：未分類錯誤中斷本次變更，需確認資源最終狀態。
處理與重試: 先讀取資源目前狀態，確認上一次變更結果，再決定是否重試。保留 request_id；結果未知時不要自動重複寫入。
示意 JSON；message 隨實際原因變化
```
{
  "request_id": "req_example",
  "error": {
    "code": "mute_conversation_failed",
    "numeric_code": "37008",
    "message": "Failed to mute conversation"
  }
}
```
pin_conversation_failed37010
置頂會話：未分類錯誤中斷本次變更，需確認資源最終狀態。
處理與重試: 先讀取資源目前狀態，確認上一次變更結果，再決定是否重試。保留 request_id；結果未知時不要自動重複寫入。
示意 JSON；message 隨實際原因變化
```
{
  "request_id": "req_example",
  "error": {
    "code": "pin_conversation_failed",
    "numeric_code": "37010",
    "message": "Failed to pin conversation"
  }
}
```
pin_message_failed36002
置頂 / 取消置頂訊息：未分類錯誤中斷本次變更，需確認資源最終狀態。
處理與重試: 先讀取資源目前狀態，確認上一次變更結果，再決定是否重試。保留 request_id；結果未知時不要自動重複寫入。
示意 JSON；message 隨實際原因變化
```
{
  "request_id": "req_example",
  "error": {
    "code": "pin_message_failed",
    "numeric_code": "36002",
    "message": "Failed to pin message"
  }
}
```
react_message_failed36004
訊息表情回應：未分類錯誤中斷本次變更，需確認資源最終狀態。
處理與重試: 先讀取資源目前狀態，確認上一次變更結果，再決定是否重試。保留 request_id；結果未知時不要自動重複寫入。
示意 JSON；message 隨實際原因變化
```
{
  "request_id": "req_example",
  "error": {
    "code": "react_message_failed",
    "numeric_code": "36004",
    "message": "Failed to react to message"
  }
}
```
request_conversation_history_failed37016
請求補拉對話歷史：未分類錯誤中斷本次變更，需確認資源最終狀態。
處理與重試: 核對 WhatsApp 私人對話與 before 錨點。request_id 僅用於 HTTP 排查。HTTP 逾時後歷史事件仍可能延遲送達；不要自動重試，也不要將沒有事件、空批次或數量不足視為完成。
示意 JSON；message 隨實際原因變化
```
{
  "request_id": "req_example",
  "error": {
    "code": "request_conversation_history_failed",
    "numeric_code": "37016",
    "message": "Failed to request conversation history"
  }
}
```
revoke_message_failed36003
撤回訊息：未分類錯誤中斷本次變更，需確認資源最終狀態。
處理與重試: 先讀取資源目前狀態，確認上一次變更結果，再決定是否重試。保留 request_id；結果未知時不要自動重複寫入。
示意 JSON；message 隨實際原因變化
```
{
  "request_id": "req_example",
  "error": {
    "code": "revoke_message_failed",
    "numeric_code": "36003",
    "message": "Failed to revoke message"
  }
}
```
run_action_failed20007
執行帳號動作：未分類錯誤中斷本次變更，需確認資源最終狀態。
處理與重試: 先讀取資源目前狀態，確認上一次變更結果，再決定是否重試。保留 request_id；結果未知時不要自動重複寫入。
示意 JSON；message 隨實際原因變化
```
{
  "request_id": "req_example",
  "error": {
    "code": "run_action_failed",
    "numeric_code": "20007",
    "message": "Failed to run account action"
  }
}
```
run_auth_action_failed20010
執行授權動作：授權動作失敗，需檢查既有流程，不代表必須重新授權。
處理與重試: 查詢目前授權流程，檢查是否需要使用者操作。不要僅因本次失敗重新發起授權，也不要向已過期或已結束的工作階段重複提交。
示意 JSON；message 隨實際原因變化
```
{
  "request_id": "req_example",
  "error": {
    "code": "run_auth_action_failed",
    "numeric_code": "20010",
    "message": "Failed to run auth action"
  }
}
```
run_runtime_action_failed20008
調整執行狀態：執行狀態動作失敗，本次回應本身無法確認連線最終狀態。
處理與重試: 查詢授權與執行狀態，再按目標狀態和渠道支援選擇重新整理、啟動或重新連線。連線問題本身不證明已登出；執行依賴連線的業務操作前確認 running。
示意 JSON；message 隨實際原因變化
```
{
  "request_id": "req_example",
  "error": {
    "code": "run_runtime_action_failed",
    "numeric_code": "20008",
    "message": "Failed to run runtime action"
  }
}
```
run_session_action_failed20009
執行工作階段動作：授權動作失敗，需檢查既有流程，不代表必須重新授權。
處理與重試: 查詢目前授權流程，檢查是否需要使用者操作。不要僅因本次失敗重新發起授權，也不要向已過期或已結束的工作階段重複提交。
示意 JSON；message 隨實際原因變化
```
{
  "request_id": "req_example",
  "error": {
    "code": "run_session_action_failed",
    "numeric_code": "20009",
    "message": "Failed to run session action"
  }
}
```
send_message_failed36001
訊息傳送失敗或結果無法確認。
處理與重試: 再次傳送前先確認原訊息或回覆是否已建立。逾時或失敗回應可能留下未知結果；後續查詢未找到回覆也不證明從未寫入。不要自動重送。
示意 JSON；message 隨實際原因變化
```
{
  "request_id": "req_example",
  "error": {
    "code": "send_message_failed",
    "numeric_code": "36001",
    "message": "Failed to send message"
  }
}
```
set_contact_note_failed35008
設定聯絡人備註：未分類錯誤中斷本次變更，需確認資源最終狀態。
處理與重試: 先讀取資源目前狀態，確認上一次變更結果，再決定是否重試。保留 request_id；結果未知時不要自動重複寫入。
示意 JSON；message 隨實際原因變化
```
{
  "request_id": "req_example",
  "error": {
    "code": "set_contact_note_failed",
    "numeric_code": "35008",
    "message": "Failed to set contact note"
  }
}
```
set_group_join_approval_mode_failed34009
設定入群審核模式：群組變更失敗，可能涉及渠道拒絕或缺少所需管理員權限。
處理與重試: 核對群組、目前成員身分、所需管理員權限與目前結果。先解決存取或權限問題，再決定是否重試變更；寫入結果未知時先核對。
示意 JSON；message 隨實際原因變化
```
{
  "request_id": "req_example",
  "error": {
    "code": "set_group_join_approval_mode_failed",
    "numeric_code": "34009",
    "message": "Failed to set group join approval mode"
  }
}
```
set_label_members_failed37015
為會話增刪標籤：未分類錯誤中斷本次變更，需確認資源最終狀態。
處理與重試: 先讀取資源目前狀態，確認上一次變更結果，再決定是否重試。保留 request_id；結果未知時不要自動重複寫入。
示意 JSON；message 隨實際原因變化
```
{
  "request_id": "req_example",
  "error": {
    "code": "set_label_members_failed",
    "numeric_code": "37015",
    "message": "Failed to set label members"
  }
}
```
unblock_contact_failed35006
解除封鎖聯絡人：未分類錯誤中斷本次變更，需確認資源最終狀態。
處理與重試: 先讀取資源目前狀態，確認上一次變更結果，再決定是否重試。保留 request_id；結果未知時不要自動重複寫入。
示意 JSON；message 隨實際原因變化
```
{
  "request_id": "req_example",
  "error": {
    "code": "unblock_contact_failed",
    "numeric_code": "35006",
    "message": "Failed to unblock contact"
  }
}
```
unmute_conversation_failed37009
恢復對話通知：未分類錯誤中斷本次變更，需確認資源最終狀態。
處理與重試: 先讀取資源目前狀態，確認上一次變更結果，再決定是否重試。保留 request_id；結果未知時不要自動重複寫入。
示意 JSON；message 隨實際原因變化
```
{
  "request_id": "req_example",
  "error": {
    "code": "unmute_conversation_failed",
    "numeric_code": "37009",
    "message": "Failed to unmute conversation"
  }
}
```
unpin_conversation_failed37011
取消置頂會話：未分類錯誤中斷本次變更，需確認資源最終狀態。
處理與重試: 先讀取資源目前狀態，確認上一次變更結果，再決定是否重試。保留 request_id；結果未知時不要自動重複寫入。
示意 JSON；message 隨實際原因變化
```
{
  "request_id": "req_example",
  "error": {
    "code": "unpin_conversation_failed",
    "numeric_code": "37011",
    "message": "Failed to unpin conversation"
  }
}
```
update_account_failed20003
更新帳號：未分類錯誤中斷本次變更，需確認資源最終狀態。
處理與重試: 先讀取資源目前狀態，確認上一次變更結果，再決定是否重試。保留 request_id；結果未知時不要自動重複寫入。
示意 JSON；message 隨實際原因變化
```
{
  "request_id": "req_example",
  "error": {
    "code": "update_account_failed",
    "numeric_code": "20003",
    "message": "Failed to update account"
  }
}
```
update_group_info_failed34006
修改群組資訊：群組變更失敗，可能涉及渠道拒絕或缺少所需管理員權限。
處理與重試: 核對群組、目前成員身分、所需管理員權限與目前結果。先解決存取或權限問題，再決定是否重試變更；寫入結果未知時先核對。
示意 JSON；message 隨實際原因變化
```
{
  "request_id": "req_example",
  "error": {
    "code": "update_group_info_failed",
    "numeric_code": "34006",
    "message": "Failed to update group info"
  }
}
```
update_group_join_requests_failed34008
核准 / 拒絕入群申請：群組變更失敗，可能涉及渠道拒絕或缺少所需管理員權限。
處理與重試: 核對群組、目前成員身分、所需管理員權限與目前結果。先解決存取或權限問題，再決定是否重試變更；寫入結果未知時先核對。
示意 JSON；message 隨實際原因變化
```
{
  "request_id": "req_example",
  "error": {
    "code": "update_group_join_requests_failed",
    "numeric_code": "34008",
    "message": "Failed to update group join requests"
  }
}
```
update_group_members_failed34005
管理群組成員：群組變更失敗，可能涉及渠道拒絕或缺少所需管理員權限。
處理與重試: 核對群組、目前成員身分、所需管理員權限與目前結果。先解決存取或權限問題，再決定是否重試變更；寫入結果未知時先核對。
示意 JSON；message 隨實際原因變化
```
{
  "request_id": "req_example",
  "error": {
    "code": "update_group_members_failed",
    "numeric_code": "34005",
    "message": "Failed to update group members"
  }
}
```
update_webhook_endpoint_failed40003
更新 Webhook 端點：未分類錯誤中斷本次變更，需確認資源最終狀態。
處理與重試: 重新提交前先讀取端點設定與帳號歸屬。PATCH 會取代設定，保留所需訂閱、簽章設定與重試策略。active 名額衝突時更新既有端點，或先停用舊端點再啟用其他端點。
示意 JSON；message 隨實際原因變化
```
{
  "request_id": "req_example",
  "error": {
    "code": "update_webhook_endpoint_failed",
    "numeric_code": "40003",
    "message": "Failed to update webhook endpoint"
  }
}
```
upsert_label_failed37013
新建或更新標籤：未分類錯誤中斷本次變更，需確認資源最終狀態。
處理與重試: 先讀取資源目前狀態，確認上一次變更結果，再決定是否重試。保留 request_id；結果未知時不要自動重複寫入。
示意 JSON；message 隨實際原因變化
```
{
  "request_id": "req_example",
  "error": {
    "code": "upsert_label_failed",
    "numeric_code": "37013",
    "message": "Failed to upsert label"
  }
}
```

501 渠道尚未實作

unsupported_by_provider30003
管道不支援此操作，請選擇能力表中支援的操作。
處理與重試: 選擇文件列為支援的渠道與動作。重複請求不會增加能力或開通內測權限。
示意 JSON；message 隨實際原因變化
```
{
  "request_id": "req_example",
  "error": {
    "code": "unsupported_by_provider",
    "numeric_code": "30003",
    "message": "Operation not supported by this provider"
  }
}
```

502 上游閘道錯誤

get_post_failed39006
貼文與留言
取得本帳號貼文：服務未能產生有效的查詢結果。
處理與重試: 保留 request_id，核對目標識別碼與帳號存取範圍。查明原因後再重試查詢；查詢失敗不等於結果為空或資源不存在。
示意 JSON；message 隨實際原因變化
```
{
  "request_id": "req_example",
  "error": {
    "code": "get_post_failed",
    "numeric_code": "39006",
    "message": "Failed to get post"
  }
}
```
list_post_comments_failed39003
貼文與留言
列出貼文第一層留言：服務未能產生有效的查詢結果。
處理與重試: 保留 request_id，核對目標識別碼與帳號存取範圍。查明原因後再重試查詢；查詢失敗不等於結果為空或資源不存在。
示意 JSON；message 隨實際原因變化
```
{
  "request_id": "req_example",
  "error": {
    "code": "list_post_comments_failed",
    "numeric_code": "39003",
    "message": "Failed to list post comments"
  }
}
```
list_posts_failed39002
貼文與留言
列出本帳號貼文：服務未能產生有效的查詢結果。
處理與重試: 保留 request_id，核對目標識別碼與帳號存取範圍。查明原因後再重試查詢；查詢失敗不等於結果為空或資源不存在。
示意 JSON；message 隨實際原因變化
```
{
  "request_id": "req_example",
  "error": {
    "code": "list_posts_failed",
    "numeric_code": "39002",
    "message": "Failed to list posts"
  }
}
```
provider_adapter_not_found30004
管道服務暫時無法使用，請檢查狀態或稍後再試；重試寫入操作前先確認上次結果。
處理與重試: 保留 request_id 與結構化錯誤碼，先排查目前操作，再決定下一步。
示意 JSON；message 隨實際原因變化
```
{
  "request_id": "req_example",
  "error": {
    "code": "provider_adapter_not_found",
    "numeric_code": "30004",
    "message": "Provider adapter unavailable"
  }
}
```
provider_unavailable30002
管道服務暫時無法使用，請檢查狀態或稍後再試；重試寫入操作前先確認上次結果。
處理與重試: 保留 request_id 與結構化錯誤碼，先排查目前操作，再決定下一步。
示意 JSON；message 隨實際原因變化
```
{
  "request_id": "req_example",
  "error": {
    "code": "provider_unavailable",
    "numeric_code": "30002",
    "message": "Provider service unavailable"
  }
}
```
reply_post_comment_failed39004
貼文與留言
核對貼文、已確認的第一層留言和錯誤分類。寫入結果未知時保留 request_id，查明後再決定是否重送；後續查詢缺少回覆不足以作為重試依據。
處理與重試: 再次傳送前先確認原訊息或回覆是否已建立。逾時或失敗回應可能留下未知結果；後續查詢未找到回覆也不證明從未寫入。不要自動重送。
示意 JSON；message 隨實際原因變化
```
{
  "request_id": "req_example",
  "error": {
    "code": "reply_post_comment_failed",
    "numeric_code": "39004",
    "message": "Failed to confirm comment reply; result may be unknown, do not automatically retry"
  }
}
```

503 服務無法使用

allocation_service_unavailable20012
帳號分配服務暫時無法使用，請稍後重試。
處理與重試: 保留 request_id 與結構化錯誤碼，先排查目前操作，再決定下一步。
示意 JSON；message 隨實際原因變化
```
{
  "request_id": "req_example",
  "error": {
    "code": "allocation_service_unavailable",
    "numeric_code": "20012",
    "message": "Allocation service is temporarily unavailable"
  }
}
```
call_service_unavailable38001
通話
通話服務無法使用，請檢查 Provider/Gateway 連線與設定。
處理與重試: 建立或結束通話前，查詢目前受管理通話及 call_id/state。preparing 不表示撥號或接通；ended 與 failed 都是終態，不要僅因 failed 重複掛斷。
示意 JSON；message 隨實際原因變化
```
{
  "request_id": "req_example",
  "error": {
    "code": "call_service_unavailable",
    "numeric_code": "38001",
    "message": "Call service unavailable"
  }
}
```
internal_auth_not_configured11006
本次請求所需的授權工作階段服務暫不可用或未設定。聯絡服務方檢查授權工作階段服務。
處理與重試: 保留 request_id 與結構化錯誤碼，先排查目前操作，再決定下一步。
示意 JSON；message 隨實際原因變化
```
{
  "request_id": "req_example",
  "error": {
    "code": "internal_auth_not_configured",
    "numeric_code": "11006",
    "message": "Internal endpoint authentication is not configured"
  }
}
```
wallet_unavailable20028
錢包資料或設定暫時無法使用；寫入失敗可能結果未知，請核對原操作。
處理與重試: 先讀取資源目前狀態，確認上一次變更結果，再決定是否重試。保留 request_id；結果未知時不要自動重複寫入。
示意 JSON；message 隨實際原因變化
```
{
  "request_id": "req_example",
  "error": {
    "code": "wallet_unavailable",
    "numeric_code": "20028",
    "message": "Wallet service is unavailable"
  }
}
```

細分數字原因

這些原因保留目前操作原有的 HTTP 狀態與 code。實際組合以介面錯誤表為準；細分原因並非適用於所有介面或渠道。

授權驗證碼被拒絕時，公開契約定義 30016，但既有授權路徑仍可能回傳 provider_invalid_request / 30001。請相容處理兩種結果，不要假設每次拒絕都會回傳 30016。

provider_operation_failed30010
渠道未能完成本次操作。message 可能在「Provider operation failed:」後附帶原始原因；原因文字可變，不是穩定的程式介面。
處理與重試: 查詢資源確認是否已刪除，再決定是否需要再次刪除。保留 request_id，按目前介面宣告的成功回應處理。
Provider operation failed
相關操作 (103)
- 刪除帳號500 · delete_account_failed適用渠道: WhatsApp
- 刪除帳號502 · provider_unavailable適用渠道: WhatsApp
- 列出聯絡人500 · list_contacts_failed適用渠道: WhatsApp
- 列出聯絡人502 · provider_unavailable適用渠道: WhatsApp
- 取得黑名單500 · list_blocklist_failed適用渠道: WhatsApp
- 取得黑名單502 · provider_unavailable適用渠道: WhatsApp
- 取得聯絡人詳情500 · get_contact_failed適用渠道: WhatsApp
- 取得聯絡人詳情502 · provider_unavailable適用渠道: WhatsApp
- 查詢聯絡人狀態500 · get_contact_membership_failed適用渠道: WhatsApp
- 查詢聯絡人狀態502 · provider_unavailable適用渠道: WhatsApp
- 列出會話500 · list_conversations_failed適用渠道: WhatsApp
- 列出會話502 · provider_unavailable適用渠道: WhatsApp
- 取得會話詳情500 · get_conversation_failed適用渠道: WhatsApp
- 取得會話詳情502 · provider_unavailable適用渠道: WhatsApp
- 列出會話標籤500 · list_conversation_labels_failed適用渠道: WhatsApp
- 列出會話標籤502 · provider_unavailable適用渠道: WhatsApp
- 列出會話成員500 · list_conversation_members_failed適用渠道: WhatsApp
- 列出會話成員502 · provider_unavailable適用渠道: WhatsApp
- 列出群組500 · list_groups_failed適用渠道: WhatsApp
- 列出群組502 · provider_unavailable適用渠道: WhatsApp
- 取得群組詳情500 · get_group_failed適用渠道: WhatsApp
- 取得群組詳情502 · provider_unavailable適用渠道: WhatsApp
- 取得群組邀請連結500 · get_group_invite_code_failed適用渠道: WhatsApp
- 取得群組邀請連結502 · provider_unavailable適用渠道: WhatsApp
- 列出入群申請500 · list_group_join_requests_failed適用渠道: WhatsApp
- 列出入群申請502 · provider_unavailable適用渠道: WhatsApp
- 查詢目前通話500 · call_control_failed適用渠道: WhatsApp
- 查詢目前通話502 · provider_unavailable適用渠道: WhatsApp
- 更新帳號500 · update_account_failed適用渠道: WhatsApp
- 取消認證500 · run_auth_action_failed適用渠道: WhatsApp
- 取消認證502 · provider_unavailable適用渠道: WhatsApp
- 確認 Passkey 授權500 · run_auth_action_failed適用渠道: WhatsApp
- 確認 Passkey 授權502 · provider_unavailable適用渠道: WhatsApp
- 提交 Passkey 憑證回應500 · run_auth_action_failed適用渠道: WhatsApp
- 提交 Passkey 憑證回應502 · provider_unavailable適用渠道: WhatsApp
- 檢查掃碼狀態500 · run_auth_action_failed適用渠道: WhatsApp
- 檢查掃碼狀態502 · provider_unavailable適用渠道: WhatsApp
- 開始掃碼認證500 · run_auth_action_failed適用渠道: WhatsApp
- 開始掃碼認證502 · provider_unavailable適用渠道: WhatsApp
- 開始驗證碼認證500 · run_auth_action_failed適用渠道: WhatsApp
- 開始驗證碼認證502 · provider_unavailable適用渠道: WhatsApp
- 新增聯絡人500 · create_contact_failed適用渠道: WhatsApp
- 新增聯絡人502 · provider_unavailable適用渠道: WhatsApp
- 封鎖聯絡人500 · block_contact_failed適用渠道: WhatsApp
- 封鎖聯絡人502 · provider_unavailable適用渠道: WhatsApp
- 設定聯絡人備註500 · set_contact_note_failed適用渠道: WhatsApp
- 設定聯絡人備註502 · provider_unavailable適用渠道: WhatsApp
- 解除封鎖聯絡人500 · unblock_contact_failed適用渠道: WhatsApp
- 解除封鎖聯絡人502 · provider_unavailable適用渠道: WhatsApp
- 請求補拉對話歷史500 · request_conversation_history_failed適用渠道: WhatsApp
- 請求補拉對話歷史502 · provider_unavailable適用渠道: WhatsApp
- 為會話增刪標籤500 · set_label_members_failed適用渠道: WhatsApp
- 為會話增刪標籤502 · provider_unavailable適用渠道: WhatsApp
- 刪除標籤500 · delete_label_failed適用渠道: WhatsApp
- 刪除標籤502 · provider_unavailable適用渠道: WhatsApp
- 新建或更新標籤500 · upsert_label_failed適用渠道: WhatsApp
- 新建或更新標籤502 · provider_unavailable適用渠道: WhatsApp
- 靜音會話500 · mute_conversation_failed適用渠道: WhatsApp
- 靜音會話502 · provider_unavailable適用渠道: WhatsApp
- 置頂會話500 · pin_conversation_failed適用渠道: WhatsApp
- 置頂會話502 · provider_unavailable適用渠道: WhatsApp
- 標記會話已讀500 · mark_conversation_read_failed適用渠道: WhatsApp
- 標記會話已讀502 · provider_unavailable適用渠道: WhatsApp
- 取消靜音500 · unmute_conversation_failed適用渠道: WhatsApp
- 取消靜音502 · provider_unavailable適用渠道: WhatsApp
- 取消置頂會話500 · unpin_conversation_failed適用渠道: WhatsApp
- 取消置頂會話502 · provider_unavailable適用渠道: WhatsApp
- 標記會話未讀500 · mark_conversation_unread_failed適用渠道: WhatsApp
- 標記會話未讀502 · provider_unavailable適用渠道: WhatsApp
- 建立群組500 · create_group_failed適用渠道: WhatsApp
- 建立群組502 · provider_unavailable適用渠道: WhatsApp
- 設定入群審核模式500 · set_group_join_approval_mode_failed適用渠道: WhatsApp
- 設定入群審核模式502 · provider_unavailable適用渠道: WhatsApp
- 核准 / 拒絕入群申請500 · update_group_join_requests_failed適用渠道: WhatsApp
- 核准 / 拒絕入群申請502 · provider_unavailable適用渠道: WhatsApp
- 退出群組500 · leave_group_failed適用渠道: WhatsApp
- 退出群組502 · provider_unavailable適用渠道: WhatsApp
- 管理群組成員500 · update_group_members_failed適用渠道: WhatsApp
- 管理群組成員502 · provider_unavailable適用渠道: WhatsApp
- 修改群組資訊500 · update_group_info_failed適用渠道: WhatsApp
- 修改群組資訊502 · provider_unavailable適用渠道: WhatsApp
- 重新連線執行環境500 · run_runtime_action_failed適用渠道: WhatsApp
- 重新連線執行環境502 · provider_unavailable適用渠道: WhatsApp
- 刷新執行狀態500 · run_runtime_action_failed適用渠道: WhatsApp
- 刷新執行狀態502 · provider_unavailable適用渠道: WhatsApp
- 啟動執行環境500 · run_runtime_action_failed適用渠道: WhatsApp
- 啟動執行環境502 · provider_unavailable適用渠道: WhatsApp
- 停止執行環境500 · run_runtime_action_failed適用渠道: WhatsApp
- 停止執行環境502 · provider_unavailable適用渠道: WhatsApp
- 建立通話500 · create_call_failed適用渠道: WhatsApp
- 建立通話502 · provider_unavailable適用渠道: WhatsApp
- 掛斷通話500 · call_control_failed適用渠道: WhatsApp
- 掛斷通話502 · provider_unavailable適用渠道: WhatsApp
- 傳送文字訊息500 · send_message_failed適用渠道: WhatsApp
- 傳送文字訊息502 · provider_unavailable適用渠道: WhatsApp
- 編輯訊息500 · edit_message_failed適用渠道: WhatsApp
- 編輯訊息502 · provider_unavailable適用渠道: WhatsApp
- 置頂 / 取消置頂訊息500 · pin_message_failed適用渠道: WhatsApp
- 置頂 / 取消置頂訊息502 · provider_unavailable適用渠道: WhatsApp
- 訊息表情回應500 · react_message_failed適用渠道: WhatsApp
- 訊息表情回應502 · provider_unavailable適用渠道: WhatsApp
- 撤回訊息500 · revoke_message_failed適用渠道: WhatsApp
- 撤回訊息502 · provider_unavailable適用渠道: WhatsApp
provider_instance_missing30014
此帳號所需的渠道執行個體缺失。這是執行個體可用性問題，不證明授權已過期。
處理與重試: 查詢授權與執行狀態，再按目標狀態和渠道支援選擇重新整理、啟動或重新連線。連線問題本身不證明已登出；執行依賴連線的業務操作前確認 running。
Provider instance is missing
相關操作 (50)
- 列出聯絡人409 · provider_not_ready適用渠道: WhatsApp
- 取得黑名單409 · provider_not_ready適用渠道: WhatsApp
- 取得聯絡人詳情409 · provider_not_ready適用渠道: WhatsApp
- 查詢聯絡人狀態409 · provider_not_ready適用渠道: WhatsApp
- 列出會話409 · provider_not_ready適用渠道: WhatsApp
- 取得會話詳情409 · provider_not_ready適用渠道: WhatsApp
- 列出會話標籤409 · provider_not_ready適用渠道: WhatsApp
- 列出會話成員409 · provider_not_ready適用渠道: WhatsApp
- 列出群組409 · provider_not_ready適用渠道: WhatsApp
- 取得群組詳情409 · provider_not_ready適用渠道: WhatsApp
- 取得群組邀請連結409 · provider_not_ready適用渠道: WhatsApp
- 列出入群申請409 · provider_not_ready適用渠道: WhatsApp
- 查詢目前通話409 · provider_not_ready適用渠道: WhatsApp
- 取消認證409 · provider_not_ready適用渠道: WhatsApp
- 確認 Passkey 授權409 · provider_not_ready適用渠道: WhatsApp
- 提交 Passkey 憑證回應409 · provider_not_ready適用渠道: WhatsApp
- 檢查掃碼狀態409 · provider_not_ready適用渠道: WhatsApp
- 開始掃碼認證409 · provider_not_ready適用渠道: WhatsApp
- 開始驗證碼認證409 · provider_not_ready適用渠道: WhatsApp
- 新增聯絡人409 · provider_not_ready適用渠道: WhatsApp
- 封鎖聯絡人409 · provider_not_ready適用渠道: WhatsApp
- 設定聯絡人備註409 · provider_not_ready適用渠道: WhatsApp
- 解除封鎖聯絡人409 · provider_not_ready適用渠道: WhatsApp
- 請求補拉對話歷史409 · provider_not_ready適用渠道: WhatsApp
- 為會話增刪標籤409 · provider_not_ready適用渠道: WhatsApp
- 刪除標籤409 · provider_not_ready適用渠道: WhatsApp
- 新建或更新標籤409 · provider_not_ready適用渠道: WhatsApp
- 靜音會話409 · provider_not_ready適用渠道: WhatsApp
- 置頂會話409 · provider_not_ready適用渠道: WhatsApp
- 標記會話已讀409 · provider_not_ready適用渠道: WhatsApp
- 取消靜音409 · provider_not_ready適用渠道: WhatsApp
- 取消置頂會話409 · provider_not_ready適用渠道: WhatsApp
- 標記會話未讀409 · provider_not_ready適用渠道: WhatsApp
- 建立群組409 · provider_not_ready適用渠道: WhatsApp
- 設定入群審核模式409 · provider_not_ready適用渠道: WhatsApp
- 核准 / 拒絕入群申請409 · provider_not_ready適用渠道: WhatsApp
- 退出群組409 · provider_not_ready適用渠道: WhatsApp
- 管理群組成員409 · provider_not_ready適用渠道: WhatsApp
- 修改群組資訊409 · provider_not_ready適用渠道: WhatsApp
- 重新連線執行環境409 · provider_not_ready適用渠道: WhatsApp
- 刷新執行狀態409 · provider_not_ready適用渠道: WhatsApp
- 啟動執行環境409 · provider_not_ready適用渠道: WhatsApp
- 停止執行環境409 · provider_not_ready適用渠道: WhatsApp
- 建立通話409 · provider_not_ready適用渠道: WhatsApp
- 掛斷通話409 · provider_not_ready適用渠道: WhatsApp
- 傳送文字訊息409 · provider_not_ready適用渠道: WhatsApp
- 編輯訊息409 · provider_not_ready適用渠道: WhatsApp
- 置頂 / 取消置頂訊息409 · provider_not_ready適用渠道: WhatsApp
- 訊息表情回應409 · provider_not_ready適用渠道: WhatsApp
- 撤回訊息409 · provider_not_ready適用渠道: WhatsApp
provider_runtime_stopped30015
渠道執行程序已停止。啟動前確認這是否為預期狀態；執行狀態停止本身不等於已登出。
處理與重試: 查詢授權與執行狀態，再按目標狀態和渠道支援選擇重新整理、啟動或重新連線。連線問題本身不證明已登出；執行依賴連線的業務操作前確認 running。
Provider runtime is stopped
相關操作 (52)
- 刪除帳號409 · provider_not_ready適用渠道: WhatsApp
- 列出聯絡人409 · provider_not_ready適用渠道: WhatsApp
- 取得黑名單409 · provider_not_ready適用渠道: WhatsApp
- 取得聯絡人詳情409 · provider_not_ready適用渠道: WhatsApp
- 查詢聯絡人狀態409 · provider_not_ready適用渠道: WhatsApp
- 列出會話409 · provider_not_ready適用渠道: WhatsApp
- 取得會話詳情409 · provider_not_ready適用渠道: WhatsApp
- 列出會話標籤409 · provider_not_ready適用渠道: WhatsApp
- 列出會話成員409 · provider_not_ready適用渠道: WhatsApp
- 列出群組409 · provider_not_ready適用渠道: WhatsApp
- 取得群組詳情409 · provider_not_ready適用渠道: WhatsApp
- 取得群組邀請連結409 · provider_not_ready適用渠道: WhatsApp
- 列出入群申請409 · provider_not_ready適用渠道: WhatsApp
- 查詢目前通話409 · provider_not_ready適用渠道: WhatsApp
- 更新帳號409 · provider_not_ready適用渠道: WhatsApp
- 取消認證409 · provider_not_ready適用渠道: WhatsApp
- 確認 Passkey 授權409 · provider_not_ready適用渠道: WhatsApp
- 提交 Passkey 憑證回應409 · provider_not_ready適用渠道: WhatsApp
- 檢查掃碼狀態409 · provider_not_ready適用渠道: WhatsApp
- 開始掃碼認證409 · provider_not_ready適用渠道: WhatsApp
- 開始驗證碼認證409 · provider_not_ready適用渠道: WhatsApp
- 新增聯絡人409 · provider_not_ready適用渠道: WhatsApp
- 封鎖聯絡人409 · provider_not_ready適用渠道: WhatsApp
- 設定聯絡人備註409 · provider_not_ready適用渠道: WhatsApp
- 解除封鎖聯絡人409 · provider_not_ready適用渠道: WhatsApp
- 請求補拉對話歷史409 · provider_not_ready適用渠道: WhatsApp
- 為會話增刪標籤409 · provider_not_ready適用渠道: WhatsApp
- 刪除標籤409 · provider_not_ready適用渠道: WhatsApp
- 新建或更新標籤409 · provider_not_ready適用渠道: WhatsApp
- 靜音會話409 · provider_not_ready適用渠道: WhatsApp
- 置頂會話409 · provider_not_ready適用渠道: WhatsApp
- 標記會話已讀409 · provider_not_ready適用渠道: WhatsApp
- 取消靜音409 · provider_not_ready適用渠道: WhatsApp
- 取消置頂會話409 · provider_not_ready適用渠道: WhatsApp
- 標記會話未讀409 · provider_not_ready適用渠道: WhatsApp
- 建立群組409 · provider_not_ready適用渠道: WhatsApp
- 設定入群審核模式409 · provider_not_ready適用渠道: WhatsApp
- 核准 / 拒絕入群申請409 · provider_not_ready適用渠道: WhatsApp
- 退出群組409 · provider_not_ready適用渠道: WhatsApp
- 管理群組成員409 · provider_not_ready適用渠道: WhatsApp
- 修改群組資訊409 · provider_not_ready適用渠道: WhatsApp
- 重新連線執行環境409 · provider_not_ready適用渠道: WhatsApp
- 刷新執行狀態409 · provider_not_ready適用渠道: WhatsApp
- 啟動執行環境409 · provider_not_ready適用渠道: WhatsApp
- 停止執行環境409 · provider_not_ready適用渠道: WhatsApp
- 建立通話409 · provider_not_ready適用渠道: WhatsApp
- 掛斷通話409 · provider_not_ready適用渠道: WhatsApp
- 傳送文字訊息409 · provider_not_ready適用渠道: WhatsApp
- 編輯訊息409 · provider_not_ready適用渠道: WhatsApp
- 置頂 / 取消置頂訊息409 · provider_not_ready適用渠道: WhatsApp
- 訊息表情回應409 · provider_not_ready適用渠道: WhatsApp
- 撤回訊息409 · provider_not_ready適用渠道: WhatsApp
provider_auth_code_rejected30016
渠道明確拒絕已提交的授權驗證碼。核對該渠道驗證碼流程與有效期；既有路徑可能回傳 30001，而非契約中的 30016。
處理與重試: 查詢目前授權流程，檢查是否需要使用者操作。不要僅因本次失敗重新發起授權，也不要向已過期或已結束的工作階段重複提交。
Provider rejected the authentication code
provider_rate_limited30017
上游渠道明確因請求過密拒絕請求。此數字分類保留目前操作既有的 HTTP 狀態與 code。
處理與重試: 暫停請求，按有次數上限的策略延後重試。此處不承諾固定等待時間或 Retry-After 處理；重試寫入前確認上次結果。
Provider rate limit exceeded
相關操作 (1)
- 新增聯絡人500 · create_contact_failed適用渠道: WhatsApp
provider_app_state_out_of_sync30018
帳號的渠道 App State 基準失去同步。這是帳號同步狀態問題，不是一般請求格式錯誤。
處理與重試: 等待渠道恢復帳號的 App State 基準，再檢查目前狀態後重試。不要僅憑此分類推斷憑證失效或重新發起授權。
Provider app state is out of sync
相關操作 (1)
- 新增聯絡人500 · create_contact_failed適用渠道: WhatsApp
provider_message_restricted30019
平台明確限制本次訊息傳送，回傳 HTTP 502、provider_unavailable、30019。不代表已確認帳號永久封禁，也沒有固定解除限制時間。
處理與重試: 對此類訊息限制停止自動重試。確認平台限制解除後才恢復傳送；沒有固定解除時間，也不應僅憑此錯誤重新授權。
Message sending is restricted by the platform
相關操作 (1)
- 傳送文字訊息502 · provider_unavailable適用渠道: WhatsApp
provider_account_restricted30020
whatsapp-protocol 同步請求以 numeric_code=30020 標識帳號登入受限，可影響工作階段匯入、執行狀態、傳送與聯絡人查詢，並保留目前操作的 HTTP 狀態與 code。不要將 WhatsApp 的 20102 回呼契約套用到此渠道。
處理與重試: 停止自動傳送與重試，引導使用者前往官方 WhatsApp 用戶端檢查並處理限制。問題解決並完成必要的重新授權後再恢復；先前為 running 不證明限制已解除。
Account login is restricted. Check the official WhatsApp app for details.
相關操作 (8)
- 刪除帳號502 · provider_unavailable適用渠道: WhatsApp Protocol
- 取得聯絡人詳情502 · provider_unavailable適用渠道: WhatsApp Protocol
- 匯入會話502 · provider_unavailable適用渠道: WhatsApp Protocol
- 重新連線執行環境502 · provider_unavailable適用渠道: WhatsApp Protocol
- 刷新執行狀態502 · provider_unavailable適用渠道: WhatsApp Protocol
- 啟動執行環境502 · provider_unavailable適用渠道: WhatsApp Protocol
- 停止執行環境502 · provider_unavailable適用渠道: WhatsApp Protocol
- 傳送文字訊息502 · provider_unavailable適用渠道: WhatsApp Protocol
provider_connection_disconnected30021
本次操作時 WhatsApp 未建立連線，message 保留原始連線原因。這不證明已登出或授權失效，也不會自動重新連線、重送或修改帳號狀態。
處理與重試: 暫停依賴連線的業務操作。先呼叫 POST /v1/accounts/{account_id}/runtime/refresh，按最新狀態恢復，確認 runtime_status=running 後再請求業務介面。重送前確認上一次寫入結果。
Account is not connected to the messaging platform
相關操作 (49)
- 刪除帳號502 · provider_unavailable適用渠道: WhatsApp
- 列出聯絡人502 · provider_unavailable適用渠道: WhatsApp
- 取得黑名單502 · provider_unavailable適用渠道: WhatsApp
- 取得聯絡人詳情502 · provider_unavailable適用渠道: WhatsApp
- 查詢聯絡人狀態502 · provider_unavailable適用渠道: WhatsApp
- 列出會話502 · provider_unavailable適用渠道: WhatsApp
- 取得會話詳情502 · provider_unavailable適用渠道: WhatsApp
- 列出會話標籤502 · provider_unavailable適用渠道: WhatsApp
- 列出會話成員502 · provider_unavailable適用渠道: WhatsApp
- 列出群組502 · provider_unavailable適用渠道: WhatsApp
- 取得群組詳情502 · provider_unavailable適用渠道: WhatsApp
- 取得群組邀請連結502 · provider_unavailable適用渠道: WhatsApp
- 列出入群申請502 · provider_unavailable適用渠道: WhatsApp
- 更新帳號500 · update_account_failed適用渠道: WhatsApp
- 取消認證502 · provider_unavailable適用渠道: WhatsApp
- 確認 Passkey 授權502 · provider_unavailable適用渠道: WhatsApp
- 提交 Passkey 憑證回應502 · provider_unavailable適用渠道: WhatsApp
- 檢查掃碼狀態502 · provider_unavailable適用渠道: WhatsApp
- 開始掃碼認證502 · provider_unavailable適用渠道: WhatsApp
- 開始驗證碼認證502 · provider_unavailable適用渠道: WhatsApp
- 新增聯絡人502 · provider_unavailable適用渠道: WhatsApp
- 封鎖聯絡人502 · provider_unavailable適用渠道: WhatsApp
- 設定聯絡人備註502 · provider_unavailable適用渠道: WhatsApp
- 解除封鎖聯絡人502 · provider_unavailable適用渠道: WhatsApp
- 請求補拉對話歷史502 · provider_unavailable適用渠道: WhatsApp
- 為會話增刪標籤502 · provider_unavailable適用渠道: WhatsApp
- 刪除標籤502 · provider_unavailable適用渠道: WhatsApp
- 新建或更新標籤502 · provider_unavailable適用渠道: WhatsApp
- 靜音會話502 · provider_unavailable適用渠道: WhatsApp
- 置頂會話502 · provider_unavailable適用渠道: WhatsApp
- 標記會話已讀502 · provider_unavailable適用渠道: WhatsApp
- 取消靜音502 · provider_unavailable適用渠道: WhatsApp
- 取消置頂會話502 · provider_unavailable適用渠道: WhatsApp
- 標記會話未讀502 · provider_unavailable適用渠道: WhatsApp
- 建立群組502 · provider_unavailable適用渠道: WhatsApp
- 設定入群審核模式502 · provider_unavailable適用渠道: WhatsApp
- 核准 / 拒絕入群申請502 · provider_unavailable適用渠道: WhatsApp
- 退出群組502 · provider_unavailable適用渠道: WhatsApp
- 管理群組成員502 · provider_unavailable適用渠道: WhatsApp
- 修改群組資訊502 · provider_unavailable適用渠道: WhatsApp
- 重新連線執行環境502 · provider_unavailable適用渠道: WhatsApp
- 刷新執行狀態502 · provider_unavailable適用渠道: WhatsApp
- 啟動執行環境502 · provider_unavailable適用渠道: WhatsApp
- 停止執行環境502 · provider_unavailable適用渠道: WhatsApp
- 傳送文字訊息502 · provider_unavailable適用渠道: WhatsApp
- 編輯訊息502 · provider_unavailable適用渠道: WhatsApp
- 置頂 / 取消置頂訊息502 · provider_unavailable適用渠道: WhatsApp
- 訊息表情回應502 · provider_unavailable適用渠道: WhatsApp
- 撤回訊息502 · provider_unavailable適用渠道: WhatsApp
group_not_found34004
此帳號下未找到群組，請核對群組 ID。
處理與重試: 核對目標識別碼、資源歸屬與目前工作區。不要將已確認缺失或無法存取的目標當作暫時服務故障自動重試。
Group not found
相關操作 (1)
- 取得會話詳情404 · conversation_not_found適用渠道: WhatsApp
group_not_participant34011
群組可能存在，但目前帳號不是成員。WhatsApp 對話詳情回傳 404 conversation_not_found / 34011 表示此帳號無法存取該群，不是暫時閘道故障。
處理與重試: 核對目標識別碼、資源歸屬與目前工作區。不要將已確認缺失或無法存取的目標當作暫時服務故障自動重試。
Account is not participating in this group
相關操作 (2)
- 取得會話詳情404 · conversation_not_found適用渠道: WhatsApp
- 取得群組詳情404 · group_not_found適用渠道: WhatsApp
group_admin_required34012
WhatsApp 群組訊息要求目前帳號具備管理員權限。請先調整群組角色，不要原樣重試。
處理與重試: 保留 request_id 與結構化錯誤碼，先排查目前操作，再決定下一步。
Group administrator privileges are required to send messages to this group
相關操作 (1)
- 傳送文字訊息502 · provider_unavailable適用渠道: WhatsApp
invalid_sticker_media36007
貼圖素材在呼叫渠道傳送前驗證失敗。回應可提供具體準備原因；numeric_code=36007 不表示已嘗試傳送。
處理與重試: 按回傳原因修正貼圖素材後再傳送。此分類發生於素材準備、呼叫渠道傳送之前，不能描述為可能已傳送但結果未知。
Invalid sticker media
相關操作 (1)
- 傳送文字訊息400 · provider_invalid_request
api_key_not_found11104
目前工作區未找到目標 API Key。更新與輪替保留 HTTP 400 及原 update_api_key_failed 或 rotate_api_key_failed；11104 僅細分原因。
處理與重試: 修改或輪替前核對目前工作區下的目標 Key。目標不存在不會因重試修復。輪替結果未知時，安全確認哪些憑證仍可用，不暴露金鑰內容。
API key not found
相關操作 (2)
- 更新 API Key 狀態400 · update_api_key_failed
- 輪替 API Key400 · rotate_api_key_failed
webhook_endpoint_not_found40006
此歸屬範圍內未找到目標 Webhook 端點。GET、PATCH 和停用保留各自操作 code 與 HTTP 500，數字原因為 40006。此細分不適用於冪等 DELETE；端點不存在時刪除回傳 204。
處理與重試: 核對目標識別碼、資源歸屬與目前工作區。不要將已確認缺失或無法存取的目標當作暫時服務故障自動重試。
Webhook endpoint not found
相關操作 (3)
- 取得 Webhook 端點500 · get_webhook_endpoint_failed
- 更新 Webhook 端點500 · update_webhook_endpoint_failed
- 停用 Webhook 端點500 · deactivate_webhook_endpoint_failed
account_restricted20102
WhatsApp 同步傳送識別到帳號登入受限，回傳 HTTP 502、provider_unavailable、20102。WhatsApp 失敗事件中同一數字語義使用 account_restricted；本次 HTTP 回應本身不會修改帳號狀態或新增回呼。
處理與重試: 停止自動傳送與重試，引導使用者前往官方 WhatsApp 用戶端檢查並處理限制。問題解決並完成必要的重新授權後再恢復；先前為 running 不證明限制已解除。
Account login is restricted. Check the official WhatsApp app for details.
相關操作 (1)
- 傳送文字訊息502 · provider_unavailable適用渠道: WhatsApp

帳號失敗事件

部分 WhatsApp account.auth.failed 事件包含選填的 data.error 物件；存在時 code、numeric_code、message 均為非空字串。請從事件內讀取，與 HTTP 錯誤回應分別處理。

舊事件及範圍外事件可能沒有 data.error；保留 last_error 相容，缺失或未知碼沿用既有帳號失敗流程。帳號列表或詳情不會因此新增此物件。這些分類不證明永久封禁，也不提供恢復期限。

安全接收並接受處理後仍回傳 2xx 確認投遞。帳號失敗與 HTTP 投遞失敗分開處理，不要因帳號失敗拒收 Webhook 而觸發重投。重試與重放沿用原規則，不對歷史事件補齊錯誤。

account_auth_failed20100

帳號授權失敗，但具體原因尚未確定。沿用既有失敗流程，不自行推斷受限或登出原因。

處理與重試: 查詢目前授權流程，檢查是否需要使用者操作。不要僅因本次失敗重新發起授權，也不要向已過期或已結束的工作階段重複提交。

示意 JSON；message 隨實際原因變化

{
  "id": "<EVENT_ID>",
  "type": "account.auth.failed",
  "provider": "whatsapp",
  "account_id": "<ACCOUNT_ID>",
  "occurred_at": "2026-10-16T00:00:00Z",
  "data": {
    "auth_status": "failed",
    "runtime_status": "disconnected",
    "event": {
      "kind": "account_auth_status",
      "auth_status": "failed",
      "runtime_status": "disconnected"
    },
    "error": {
      "code": "account_auth_failed",
      "numeric_code": "20100",
      "message": "Account authentication failed. The specific cause could not be determined."
    }
  }
}

account_logged_out20101

目前帳號工作階段已失效。引導使用者透過此渠道支援的流程重新授權。

處理與重試: 引導使用者透過此渠道支援的流程重新授權。授權完成後另查執行狀態，確認連線就緒，再恢復依賴連線的操作。

示意 JSON；message 隨實際原因變化

{
  "id": "<EVENT_ID>",
  "type": "account.auth.failed",
  "provider": "whatsapp",
  "account_id": "<ACCOUNT_ID>",
  "occurred_at": "2026-10-16T00:00:00Z",
  "data": {
    "auth_status": "failed",
    "runtime_status": "disconnected",
    "event": {
      "kind": "account_auth_status",
      "auth_status": "failed",
      "runtime_status": "disconnected"
    },
    "error": {
      "code": "account_logged_out",
      "numeric_code": "20101",
      "message": "The account session is no longer valid. Reauthorization is required."
    }
  }
}

account_restricted20102

此 WhatsApp account.auth.failed 事件以 data.error.code=account_restricted、numeric_code=20102 標識目前登入受限。不證明永久封禁，也不說明何時可恢復。

處理與重試: 停止自動傳送與重試，引導使用者前往官方 WhatsApp 用戶端檢查並處理限制。問題解決並完成必要的重新授權後再恢復；先前為 running 不證明限制已解除。

示意 JSON；message 隨實際原因變化

{
  "id": "<EVENT_ID>",
  "type": "account.auth.failed",
  "provider": "whatsapp",
  "account_id": "<ACCOUNT_ID>",
  "occurred_at": "2026-10-16T00:00:00Z",
  "data": {
    "auth_status": "failed",
    "runtime_status": "disconnected",
    "event": {
      "kind": "account_auth_status",
      "auth_status": "failed",
      "runtime_status": "disconnected"
    },
    "error": {
      "code": "account_restricted",
      "numeric_code": "20102",
      "message": "Account login is restricted. Check the official WhatsApp app for details."
    }
  }
}