集成故障排除

问题	解决方法
MCP 初始化成功，但执行返回 401	设置 `SOCQ_API_KEY` 或配置 Bearer 令牌。参见集成身份验证。
找不到类型化工具（Typed tools）	检查 `platforms` 或 `tools` 过滤条件，然后重新启动客户端。参见选择 MCP 工具。
MCP 调用返回任务 ID	这是正常行为。继续调用 `socq_get_task`；参见任务和结果。
轮询超时	使用同一个任务 ID 继续查询，不要重新提交。
400 参数校验错误	运行 `socq describe PLATFORM/RESOURCE` 或检查 API 的参数结构，并删除不支持的字段。
403	检查 API 密钥状态和 IP 白名单。
409	使用新的幂等密钥，或使用完全相同的输入重试原请求。
402 或 429	检查账户积分和 API 密钥限制，并遵循 API 错误中的重试建议。
CLI 动态参数被拒绝	刷新能力目录（Capability Catalog），并使用其中 JSON Schema 定义的字段名。

对于协议层问题，请确认代理保留 Authorization、Accept、Content-Type 和 MCP-Protocol-Version 请求头，并将请求路由到准确的 /mcp 路径，避免重复添加 /mcp。

​集成故障排除