开发者/错误码与限速
错误码、限速和套餐
本机接口和 /v1/call 会返回哪些错误、什么意思、Agent 该怎么处理。
错误码
| HTTP | error | 意思 | 怎么办 |
|---|---|---|---|
| 401 | unauthorized | 没带令牌或令牌不对 | 重新复制令牌；重置过的要重新接入 |
| 402 | plan_required | 免费版调了 write / public 级能力（code: publish.agent，带 upgradeUrl） | 告诉用户要升级，别重试 |
| 403 | blocked | 这个能力不开放（密钥、登录、付款、要人操作） | 让用户自己在字流里操作 |
| 403 | public_disabled | 会公开的操作，用户没打开「允许 AI 代点发布」 | 请用户去设置里打开，或让用户自己点 |
| 409 | confirm_required | 会公开的操作没带 confirm: true | 先问用户，同意后带上 confirm 再调 |
| 404 | unknown_channel / not_found | 能力名或路径不对 | 查 /v1/catalog |
| 429 | rate_limited | 超过限速，带 reason 和 retryAfterSec | 等 retryAfterSec 秒再调 |
| 503 | bridge_not_ready | 字流刚启动还没准备好 | 等几秒 |
| 400 | 具体原因 | 参数不对，或这个能力执行时出错（原因是中文，可以直接给用户看） | 按原因改参数 |
限速
- 每分钟最多 120 次调用。
- 会花云点的能力（目录里
costsPoints: true）每分钟最多 15 次。 - 限速是防 Agent 写错进死循环把云点烧光；正常干活碰不到。
套餐和云点
| 免费版 | 创作者版 / 矩阵版 | |
|---|---|---|
| read 只读能力 | 可以 | 可以 |
| write 写稿、剪辑、送发布、改设定 | 不可以（402） | 可以 |
| public 会公开的操作 | 不可以 | 用户打开开关 + confirm |
| 云点 | 和在界面上用一样：字流 AI、转写、生图按用量扣；用户用自己的模型密钥就不扣 | 同左 |
大活之前可以先调 ai:pointEstimates 看大概花多少，再调 entitlements:get 看还剩多少。