参考

错误码参考

结合当前操作读取 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."
    }
  }
}