修复 AI 智能体和 API 错误
Clevera 的 API、MCP 服务器和 AI agents & API 页面中，AI 智能体、脚本或用户可能看到的每条消息，按原因分类：Token、套餐、权限、付费工作、速率限制、冲突和连接应用，并附带解决方法。
更新于 阅读需 6 分钟
当 Clevera 拒绝智能体的调用时，智能体会收到一个代码和一条说明如何操作的消息。本文列出了智能体、脚本或人员在使用“AI 智能体与 API”时可能会看到的每条消息、其原因以及修复方法。通过 REST API，代码位于 error.code 中；通过 MCP，相同的消息会作为工具错误返回。
令牌未被接受
| 消息 | 代码 | 原因 | 修复 |
|---|---|---|---|
| "Send a Clevera agent token (Authorization: Bearer clv_agent_…) or connect through OAuth. Create a token in Integrations → AI agents & API." | unauthenticated |
未发送令牌。 | 发送 Authorization: Bearer <token>。检查智能体运行位置是否设置了 CLEVERA_TOKEN。 |
| "That is not a valid Clevera agent token. Create one in Integrations → AI agents & API." | unauthenticated |
值输入错误、被截断或不是 Clevera 令牌。 | 重新粘贴完整令牌。 |
| "Unknown token. It may have been deleted; create a new one in Integrations → AI agents & API." | unauthenticated |
Clevera 不识别此令牌。 | 创建一个新令牌。 |
| "OAuth connector tokens work on the MCP server only. Use a static token for the REST API." | unauthenticated |
在 REST API 上使用了已连接应用的登录信息。 | 为 REST 使用 API 令牌。 |
| "This token has expired. Create a new one in Integrations → AI agents & API." | token_expired |
令牌有效期已过。 | 创建一个新令牌。 |
| "This token was revoked." | token_revoked |
有人撤销了它、它被重新生成、其所有者离开，或 Clevera 撤销了它。 | 查看 令牌停止工作的原因。 |
| "The account that owns this token is suspended." | token_revoked |
令牌所有者的账户被暂停。 | 联系支持团队。 |
| "This token can't be used from this IP address." | ip_not_allowed |
调用来自令牌 IP 白名单之外。 | 从允许的地址运行智能体，或使用新地址创建令牌。 |
套餐不包含此功能
“AI 智能体与 API”（令牌、已连接的应用和 Webhook）包含在专业版、商业版和自定义套餐中。在免费版和入门版中，页面会显示“AI 智能体与 API 包含在专业版中”，并提供 升级至专业版 按钮。升级后，现有的令牌、应用和 Webhook 将恢复工作；不会删除任何内容。
| 消息 | 代码 | 原因 | 修复 |
|---|---|---|---|
| "The agent API is not on this workspace's plan. It is on Pro and up." | plan_locked (HTTP 403) |
工作区处于免费版或入门版，或已降级至这些版本。每个令牌和已连接的应用调用都会被拒绝。 | 升级至专业版。未过期的令牌将恢复工作。 |
| Claude 或 ChatGPT 仅显示无法连接，或其 Clevera 工具失败 | plan_locked (后台) |
相同的套餐拒绝，应用将其显示为通用连接错误。 | 将工作区升级至专业版，然后在应用中重试。 |
| "The API and agent access are not on your plan." | — | 在非专业版套餐中创建令牌，或在智能体请求上点击 批准。 | 升级至专业版。拒绝 仍然有效。 |
| "The API and agent access are on Pro and up." / "Claude.ai and ChatGPT connectors are on Pro and up." / "Webhooks are on Pro and up." | — | 免费版或入门版中锁定的控件。 | 升级至专业版。 |
| workspace "(plan doesn’t include connected apps)" / "This workspace’s plan does not include connected apps." | — | 将 Claude 或 ChatGPT 连接到非专业版工作区。 | 升级，或在连接屏幕上选择另一个工作区。 |
| 重新生成密钥 打开升级对话框 | — | 密钥无法在非专业版中重新生成。 | 升级至专业版，或撤销令牌。 |
| "Webhooks are not on your plan." | — | 在非专业版中 发送测试事件 或 重新投递。不会发送任何内容；等待重试将以 plan_locked 失败。 |
升级至专业版。 |
| "Your plan does not include paid agent work. Upgrade to let agents start it." | plan_locked |
在不支持的套餐上进行付费工作。 | 升级至专业版。 |
令牌无权执行
| 消息 | 代码 | 原因 | 修复 |
|---|---|---|---|
| "This token lacks the ability ability. Ask the workspace member who owns it for a token that has it." | forbidden_ability |
令牌缺少此调用所需的权限。 | 创建具有该权限的令牌。请参阅 智能体权限。 |
| "The token owner's current role in this workspace does not allow ability." | forbidden_role |
自令牌创建以来，所有者的角色发生了变化。令牌显示 超出角色权限。 | 由具有相应角色的人员创建令牌。 |
| "Your role can’t grant some of these abilities." / "Your role can’t grant: abilities." | — | 创建超出您角色权限的令牌。 | 取消勾选它们，或咨询所有者或管理员。 |
| "You can't do this in this workspace." | forbidden |
所有者的角色或访问权限不允许对此项目执行此操作。 | 检查所有者的角色和集合访问权限。 |
| "The token owner can view this article but not edit it (collection access)." | forbidden_item |
项目位于所有者仅能查看的集合中。 | 授予所有者对该集合的编辑权限。 |
| "No item with that id in this token's scope. List or search first and use a returned id." | not_found |
ID 错误，或者项目在令牌的站点或所有者的访问权限之外。 | 先列出或搜索，然后使用返回的 ID。 |
| "This content is live on a published site, so changing it needs the site:publish ability." | live_content_needs_publish |
在没有发布权限的情况下编辑（或翻译）已发布的文档站点文章。 | 授予令牌 site:publish，或让其提交以供审核。 |
| "This article is also shown on a site this token cannot change. …" | shared_outside_scope |
文章出现在令牌站点之外的站点上。 | 使用覆盖所有显示该文章站点的令牌，或留下审核备注。 |
| "This site is paused or offline and read-only. A workspace owner can re-activate it in Docs." | site_paused |
文档站点已暂停。 | 重新激活站点。 |
付费工作被拒绝
| 消息 | 代码 | 原因 | 修复 |
|---|---|---|---|
| "This would pass the token's spend cap. A workspace admin can raise it." | cap_exceeded |
报价不符合令牌的 每个任务、每天 或 每月 上限。 | 等待下一天或下个月，或创建具有更高上限的令牌。 |
| 关于额度用尽的消息 | insufficient_credits |
工作区额度不足。 | 购买额度或等待额度发放。 |
| "Your workspace cannot spend credits right now." | plan_locked |
账单限制了支出，例如有待支付款项。 | 检查 账单。 |
| "This quote has expired. Ask for a new quote." | quote_expired |
报价有效期为 15 分钟。 | 索取新报价。 |
| "This quote was already used. Ask for a new quote." | quote_used |
一个报价仅能启动一个任务。 | 索取新报价。 |
| "This quote is for another kind of job." | quote_mismatch |
例如，视频报价被用于启动剪辑。 | 使用匹配的启动调用。 |
| "Another start is being checked. Try again in a moment." | busy |
同一时刻有两个启动请求。 | 片刻后重试。 |
任务处于 needs_input 等待状态 |
— | 正在 智能体请求 中等待批准。 | 所有者或管理员在 24 小时内批准或拒绝它。 |
任务以 expired 结束 |
— | 24 小时内无人处理。 | 重新开始并批准它。 |
| "This job can no longer be canceled." | not_cancelable |
任务已完成或已超过可取消的时间点。 | — |
请求视频时的常见输入消息：“This recording is still processing. Please wait until it is ready.”（录制内容仍在处理中。请等待其就绪。），“Choose how_to, product_demo, cleanup or styled_video.”（选择 how_to、product_demo、cleanup 或 styled_video。），“Choose 1080p, 2k or 4k.”（选择 1080p、2k 或 4k。），“Exports are always 60 fps.”（导出始终为 60 fps。），“This item is an article; only videos can be exported.”（此项目为文章；仅可导出视频。），“Social clips cannot be translated by agents yet.”（智能体尚无法翻译社交剪辑。），“This language is already translated.”（该语言已翻译。），“That material was not found in this workspace. Upload it first.”（在此工作区中未找到该素材。请先上传。）
请求过多
| 消息 | 代码 | 限制 |
|---|---|---|
| "This token is over its request rate. Wait and retry." | rate_limited |
每个令牌每分钟 300 次请求 |
| "This workspace is over its agent request rate. Wait and retry." | rate_limited |
每个工作区每分钟 1,200 次请求 |
| "Too many writes from this token. Wait and retry." | rate_limited |
每个令牌每分钟 60 次写入 |
| "This token reached its daily write limit. Try again tomorrow." | rate_limited |
每个令牌每天 2,000 次写入 |
| "This token reached its hourly publish limit. Try again later." | rate_limited |
每个令牌每小时 10 次发布 |
| "Too many uploads from this token. Wait and retry." | rate_limited |
每分钟 30 次上传 |
| "This token reached its daily upload volume. Try again tomorrow." | rate_limited |
每个令牌每天 500 MB |
| "Writes from this token are paused after an unusual burst of changes. The workspace owner was notified." | rate_limited |
异常活动：写入暂停 10 分钟 |
| "Too many requests. Wait and retry." | rate_limited |
每个 IP 地址每分钟 60 次（无有效令牌） |
付费启动项也限制为每个令牌每小时 20 次，每个工作区每天 100 次。每个 429 都有一个 Retry-After 标头；请等待相应时长。
内容与重试
| 消息 | 代码 | 修复 |
|---|---|---|
| "The content changed since you read it. Re-read it …, merge your change and retry with that id." | revision_conflict |
代理会重新读取页面并重新应用其更改。 |
| "This idempotency key was used for a different request." | idempotency_conflict / idempotency_key_reused |
为新请求使用新的 Idempotency-Key。 |
| — | idempotency_in_progress |
使用此密钥的第一个请求仍在运行。请等待，然后使用相同的密钥重试。 |
令牌与页面
| 情况 | 原因 | 修复 |
|---|---|---|
| 新令牌 已禁用 | "Your workspace has reached its limit of 50 active tokens. Revoke one first." | 撤销一个你不使用的令牌。 |
| 没有 重新生成密钥 选项 | 只有令牌的创建者才能重新生成它，且仅限一次。"Only the person who created this token can regenerate it. You can revoke it." | 重新生成较新的令牌，或创建一个新令牌。 |
| "This token was already regenerated, revoked or has expired; use its replacement or create a new one." | 密钥之前已被重新生成。 | 使用替换令牌。 |
| 你看不到同事的令牌 | 只有所有者和管理员才能看到所有令牌。 | 请咨询所有者或管理员。 |
| 你无法批准请求："An owner or admin decides" | 只有所有者和管理员才能批准支出。 | 请咨询所有者或管理员。 |
| "Only owners and admins manage webhooks" | 你的角色无法管理 Webhook。 | 请咨询所有者或管理员。 |
连接 Claude 或 ChatGPT
| 屏幕显示 | 修复 |
|---|---|
| "This request expired" | "Too much time passed since the app asked. Start connecting again from the app." |
| "This app isn’t registered" | 在应用中移除连接器并重新添加。 |
| "This request can’t be trusted" | "Nothing was shared. Start connecting again from the app." 如果持续出现此问题，请勿连接。 |
| "Choose a workspace you are a member of." | 选择一个你所属的工作区。 |
| "Revoked: token reuse detected" on a connected app | 应用的登录信息被重复使用，因此 Clevera 已将其撤销。请重新连接该应用。 |
仍然卡住
请联系支持团队，并提供错误信息中的 request_id、令牌名称（切勿提供令牌本身）以及调用时间。