參考

錯誤碼參考

請按目前操作一併讀取 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."
    }
  }
}