> ## Documentation Index
> Fetch the complete documentation index at: https://docs.poyo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 集成故障排查

> PoYo MCP、CLI 和各类集成的常见失败情况。

# 错误

| HTTP 状态码 | 含义 |
| - | - |
| `400` | 输入、筛选参数或游标无效 |
| `401` | API Key 缺失或无效 |
| `402` | 积分不足 |
| `403` | 该 API Key 无权使用此模型或任务 |
| `404` | 未找到模型能力或任务 |
| `429` | 超出速率或积分限制 |
| `503` | 目录元数据不完整或不可用 |

## MCP 错误

工具输入错误和业务失败以 MCP 工具错误的形式返回，以便调用方模型检查并修正。

常见标识符包括：

* `model_capability_not_found`
* `mcp_models_and_categories_are_mutually_exclusive`
* `mcp_model_filter_limit`
* `mcp_category_filter_limit`
* `mcp_typed_tool_limit`

## 是否重试

| 情况 | 是否重试 | 处理方式 |
| - | - | - |
| schema 无效或模型未知 | 否 | 刷新目录并修正请求 |
| API Key 无效或模型被禁止 | 否 | 修正凭据或模型访问权限 |
| 积分不足 | 否 | 充值积分或选择成本更低的模型 |
| 被限流 | 是 | 遵循 `Retry-After` 并退避 |
| 供应商或服务的暂时性故障 | 视情况 | 检查失败原因，并在重新提交前确认是否已创建任务 |
| 本地等待超时且已有任务 ID | 不要重新提交 | 继续检查已有任务 |

不要盲目重试付费失败的请求。提交重试不会去重，可能会创建另一个任务并再次扣费。重新提交前，请检查标准化错误，并确认原始请求是否已创建任务。

## 工具缺失

修改 URL 或筛选参数后，重启 MCP 服务器或开启新的客户端会话。确认没有同时使用 `models` 和 `categories`，且没有超出类型化工具的数量限制。

## 对话没有流式输出

这是 `poyo_chat` 的预期行为：它返回一个完整的 Tool Result。如需 token 级 SSE，请使用原生对话 REST 接口或 `poyo chat --stream`。

## 任务似乎卡住了

保留任务 ID，并使用退避策略再次检查。客户端超时或断开连接并不代表远端任务失败。如果任务状态在超过该模型预期处理时间后仍未变化，请携带任务 ID 联系支持。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.