修正 AI 代理人與 API 錯誤
整理 AI 代理人、指令碼或人員在使用 Clevera 的 API、MCP 伺服器以及「AI 代理人與 API」頁面時可能遇到的每則訊息，並依原因分類：Token、方案、權限、付費任務、速率限制、衝突與應用程式連接，並提供修正方式。
更新於 閱讀時間 6 分鐘
當 Clevera 拒絕代理人的呼叫時，代理人會收到一個代碼和一則說明如何處理的訊息。本文列出了代理人、指令碼或人員在使用「AI 代理人與 API」時可能看到的每則訊息、其原因以及修正方式。透過 REST API，代碼位於 error.code；透過 MCP，相同的訊息會以工具錯誤的形式回傳。
Token 未被接受
| 訊息 | 代碼 | 原因 | 修正方式 |
|---|---|---|---|
| "Send a Clevera agent token (Authorization: Bearer clv_agent_…) or connect through OAuth. Create a token in Integrations → AI agents & API." | unauthenticated |
未傳送 Token。 | 傳送 Authorization: Bearer <token>。檢查代理人執行處是否已設定 CLEVERA_TOKEN。 |
| "That is not a valid Clevera agent token. Create one in Integrations → AI agents & API." | unauthenticated |
數值輸入錯誤、被截斷或非 Clevera Token。 | 再次貼上完整 Token。 |
| "Unknown token. It may have been deleted; create a new one in Integrations → AI agents & API." | unauthenticated |
Clevera 無法識別此 Token。 | 建立新的 Token。 |
| "OAuth connector tokens work on the MCP server only. Use a static token for the REST API." | unauthenticated |
在 REST API 上使用了已連接應用程式的登入資訊。 | 對 REST 使用 API Token。 |
| "This token has expired. Create a new one in Integrations → AI agents & API." | token_expired |
Token 已過期。 | 建立新的 Token。 |
| "This token was revoked." | token_revoked |
Token 被撤銷、重新產生、擁有者離職，或由 Clevera 撤銷。 | 查看 Token 停止運作的原因。 |
| "The account that owns this token is suspended." | token_revoked |
Token 擁有者的帳戶已停權。 | 聯絡支援團隊。 |
| "This token can't be used from this IP address." | ip_not_allowed |
呼叫來自 Token 的 IP 允許清單之外。 | 從允許的位址執行代理人，或使用新位址建立 Token。 |
方案未包含此功能
「AI 代理人與 API」（Token、已連接應用程式與 Webhook）包含在 Pro、Business 與 Custom 方案中。在 Free 與 Starter 方案中，頁面會顯示「AI 代理人與 API 包含在 Pro 方案中」，並提供「升級至 Pro」按鈕。升級後，現有的 Token、應用程式與 Webhook 將恢復運作；不會刪除任何內容。
| 訊息 | 代碼 | 原因 | 修正方式 |
|---|---|---|---|
| "The agent API is not on this workspace's plan. It is on Pro and up." | plan_locked (HTTP 403) |
工作區為 Free 或 Starter 方案，或已降級至此。所有 Token 與應用程式連接呼叫皆被拒絕。 | 升級至 Pro。未過期的 Token 將恢復運作。 |
| Claude 或 ChatGPT 僅顯示無法連接，或其 Clevera 工具失敗 | plan_locked (背景) |
同樣的方案拒絕，應用程式顯示為一般連接錯誤。 | 將工作區升級至 Pro，然後在應用程式中重試。 |
| "The API and agent access are not on your plan." | — | 在非 Pro 方案下建立 Token，或點擊代理人請求上的「核准」。 | 升級至 Pro。「拒絕」功能仍可使用。 |
| "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." | — | Free 或 Starter 方案中的鎖定控制項。 | 升級至 Pro。 |
| workspace "(plan doesn’t include connected apps)" / "This workspace’s plan does not include connected apps." | — | 將 Claude 或 ChatGPT 連接到非 Pro 方案的工作區。 | 升級，或在連接畫面選擇其他工作區。 |
| 「重新產生密鑰」開啟升級對話框 | — | 非 Pro 方案無法重新產生密鑰。 | 升級至 Pro，或撤銷 Token。 |
| "Webhooks are not on your plan." | — | 在非 Pro 方案下執行「傳送測試事件」或「重新傳送」。未傳送任何內容；等待重試將以 plan_locked 失敗。 |
升級至 Pro。 |
| "Your plan does not include paid agent work. Upgrade to let agents start it." | plan_locked |
在未包含付費任務的方案中執行付費任務。 | 升級至 Pro。 |
Token 未獲授權執行
| 訊息 | 代碼 | 原因 | 修正方式 |
|---|---|---|---|
| "This token lacks the ability ability. Ask the workspace member who owns it for a token that has it." | forbidden_ability |
Token 缺乏此呼叫所需的權限。 | 建立具有該權限的 Token。請參閱 代理人權限。 |
| "The token owner's current role in this workspace does not allow ability." | forbidden_role |
自 Token 建立後，擁有者的角色已變更。Token 顯示「超出角色權限」。 | 由具備正確角色的人員建立 Token。 |
| "Your role can’t grant some of these abilities." / "Your role can’t grant: abilities." | — | 建立超出您角色權限的 Token。 | 取消勾選，或詢問擁有者或管理員。 |
| "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 錯誤，或項目位於 Token 的網站範圍或擁有者存取權之外。 | 先列出或搜尋，然後使用回傳的 ID。 |
| "This content is live on a published site, so changing it needs the site:publish ability." | live_content_needs_publish |
在沒有發佈權限的情況下編輯（或翻譯）已發佈的網站文章。 | 給予 Token site:publish 權限，或讓其提交審核。 |
| "This article is also shown on a site this token cannot change. …" | shared_outside_scope |
文章出現在 Token 網站範圍之外的網站上。 | 使用涵蓋所有顯示該文章網站的 Token，或留下審核註記。 |
| "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 |
報價超過 Token 的「每個任務」、「每日」或「每月」上限。 | 等待隔天或下個月，或建立具有更高上限的 Token。 |
| 關於點數用盡的訊息 | 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 |
任務已完成或已超過可取消的時間點。 | — |
請求影片時常見的輸入訊息：「此錄影仍在處理中。請等待其準備就緒。」、「請選擇 how_to、product_demo、cleanup 或 styled_video。」、「請選擇 1080p、2k 或 4k。」、「匯出格式皆為 60 fps。」、「此項目為文章；僅能匯出影片。」、「代理人目前無法翻譯社群剪輯。」、「此語言已翻譯完成。」、「在此工作區中找不到該素材。請先上傳。」
請求過多
| 訊息 | 代碼 | 限制 |
|---|---|---|
| "This token is over its request rate. Wait and retry." | rate_limited |
每個 Token 每分鐘 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 |
每個 Token 每分鐘 60 次寫入 |
| "This token reached its daily write limit. Try again tomorrow." | rate_limited |
每個 Token 每日 2,000 次寫入 |
| "This token reached its hourly publish limit. Try again later." | rate_limited |
每個 Token 每小時 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 |
每個 Token 每日 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 |
未使用有效 Token 的 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、權杖名稱（切勿提供權杖本身）以及呼叫發生的時間。