MCP 错误分为传输、身份验证、范围与套餐、配额与工具调用几组。请先匹配下方代码，再修改客户端代码。
服务不可用时应如何处理？
503 响应表示服务可用性问题。确认公开连接地址，暂停调用，稍后使用有上限的退避重试。若问题持续，请向支持人员提供时间戳和脱敏请求 ID。
主机或来源检查为何失败？
- 使用准确的地址
https://app.dureach.com/mcp和支持 streamable HTTP 的 MCP 客户端。 - 为目标工作区完成 OAuth 授权；凭据应保存在客户端受保护的凭据存储或服务器端密钥管理器中。
- 若主机或来源被拒绝，检查连接地址并联系支持人员。不要删除或伪造安全标头以绕过拒绝。
- 保留响应中的
request_id以便排查；不要在共享日志中包含令牌或结果行。
身份验证为何失败？
| 现象 | 含义 | 修复方法 |
|---|---|---|
401，无 request_id 详情 | 令牌缺失、过期、已撤销或受众错误。 | 重新完成 OAuth 同意；确认受众为 /mcp 资源（/.well-known/oauth-protected-resource/mcp）；发送 Authorization: Bearer YOUR_OAUTH_ACCESS_TOKEN。 |
REST API 密钥在别处可用，在 /mcp 被拒绝 | API 密钥对 MCP 无效。 | 使用 OAuth Bearer 令牌。API 密钥仅对其文档化 REST 路由有效。 |
workspace_context_required (403) | X-Workspace-ID 与令牌工作区不一致。 | 发送令牌所属工作区 ID，或省略该标头。令牌永不跨工作区。 |
工具为何缺失或被拒绝？
| 现象 | 含义 | 修复方法 |
|---|---|---|
tools/list 中缺失工具 | 此连接不可使用。 | 请与管理员审核已授予的权限和工作区访问资格。 |
Unknown tool (INVALID_PARAMS) | 名称缺少 dureach. 前缀，或不是 14 个工具之一。 | 发送完整名称（例如 dureach.trade.search）。别名 companies.list 解析为 companies.search；其他名称会被拒绝。 |
scope_required | 令牌缺少工具所需范围。 | 审核并仅授予工具所需权限。不要仅为消除错误而扩大权限。 |
plan_capability_required (403) | 工作区缺少智能体平台能力。 | 请管理员启用该能力或更换套餐。 |
invalid_arguments | 值超出范围、查询过短、字段未知或 SQL 过大。 | 对照工具表格；查询需要 3 个以上字符，页码与条数须保持在范围内，SQL 须在 16 KiB 以内并符合只读语法。 |
company_not_found | companies.read ID 未知。 | 确认 UUID 来自同一工作区的 companies.search。 |
policy_not_found / policy_not_authorized | R3 发送指定的策略未知、已撤销、已过期或不匹配。 | 传入绑定到此 OAuth 客户端的 ACTIVE 经所有者复核的常设策略的 policy_id，先运行 dry_run: true，再使用同一幂等键重试。 |
policy_budget_exceeded / policy_daily_cap_exceeded | 策略发送上限已用完。 | 等待下一个每日窗口，或请所有者复核上限；不要为规避上限而将发送拆分到新策略。 |
recipient_suppressed / recipient_already_attempted | 收件人已退订、退信、非活跃线索，或在此策略下已尝试发送。 | 移除该收件人并检查抑制状态；不要在新策略下重试同一收件人。 |
result_too_large | 传输结果超过 1 MiB。 | 减少所选列、收窄筛选条件或降低 limit。 |
quota_exceeded (429) | 分钟、小时或每日预算已用完。 | 遵守 Retry-After；详情包含 limit_type、reset_at、retry_after。参见《MCP 审批、策略与配额》。 |
| 请求体被拒绝或截断 | 请求超过 256,000 字节。 | 缩短 SQL 或参数；拆分调用。 |
应向支持团队发送什么？
请包含 request_id（或 x-request-id）、时间戳、工具名称、page／limit 或 SQL 结构（尽可能不含客户标识）、HTTP 状态与错误代码。不要包含 Bearer 令牌、完整联系人行或 Webhook 负载。