# 错误与限制

> 常见返回状态、余额不足、限流、幂等重试，以及本人参与工具的边界。

更新:2026-06-29
页面:https://herline.vip/developers/errors

---


MCP 工具会尽量返回结构化状态，方便 agent 判断下一步动作。调试和反馈时，请保留 `request_id`。

## 常见返回状态

| status               | 含义                     | 你的 agent 该做什么                   |
| -------------------- | ------------------------ | ------------------------------------- |
| `ok`                 | 调用成功                 | 读 `data`；异步能力据 `task_id` 轮询  |
| `insufficient_units` | 余额不足                 | 据 `recovery.options` 提示升级 / 充值 |
| `unauthorized`       | 未授权或令牌失效         | 重新走授权流程                        |
| `forbidden`          | 当前会员档没有这个能力   | 提示对应档位才可用                    |
| `not_found`          | 目标资源不存在或不属于你 | 核对标识                              |
| `rate_limited`       | 触发频率限制             | 退避后重试                            |
| `error`              | 服务端异常               | 带 `request_id` 反馈，稍后重试        |

## 余额不足

余额不足会返回 `required`、`remaining` 和 `recovery.options`。agent 应明确告知用户需要升级、充值或开启自动充值，详见[调用与计费](/developers/billing)。

## 调用频率

接口有频率限制。MCP 调用与网页端分区限流；API Key 路径按 key 隔离。触发 `rate_limited` 后，请指数退避重试。

## 幂等与重试

生产类工具应携带 `idempotency_key`。网络抖动或客户端超时时，优先使用原幂等键重试，避免重复扣费和重复任务。

## 能力边界

陪练、排练、测评只开放发起和读取结果。无论使用 OAuth 还是 API Key，都不能通过 MCP 执行逐轮练习或代答测评。详见[能力与边界](/developers/capabilities)。

## 出问题怎么反馈

通过产品内客服入口反馈，并附上 `request_id`、工具名、调用时间和主要参数摘要。