| 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 定义的字段名。 |
