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(토큰, 연결된 앱 및 웹후크)는 Pro, Business 및 Custom 플랜에서 제공됩니다. Free 및 Starter 플랜에서는 페이지에 "AI 에이전트 & API는 Pro에 포함되어 있습니다"라는 문구와 함께 Pro로 업그레이드 버튼이 표시됩니다. 업그레이드하면 기존 토큰, 앱 및 웹후크가 다시 작동하며, 삭제되는 항목은 없습니다.
| 메시지 |
코드 |
원인 |
해결 방법 |
| "The agent API is not on this workspace's plan. It is on Pro and up." |
plan_locked (HTTP 403) |
워크스페이스가 Free 또는 Starter 플랜이거나 해당 플랜으로 변경됨. 모든 토큰 및 연결된 앱 호출이 거부됨. |
Pro로 업그레이드하세요. 만료되지 않은 토큰이 다시 작동합니다. |
| Claude 또는 ChatGPT가 연결할 수 없다고 표시하거나 Clevera 도구가 실패함 |
plan_locked (내부) |
동일한 플랜 제한으로, 앱에서는 일반적인 연결 오류로 표시됨. |
워크스페이스를 Pro로 업그레이드한 후 앱에서 다시 시도하세요. |
| "The API and agent access are not on your plan." |
— |
Pro 플랜이 아닌 상태에서 토큰을 생성하거나 에이전트 요청에서 승인을 클릭함. |
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로 업그레이드하세요. |
| 워크스페이스 "(plan doesn’t include connected apps)" / "This workspace’s plan does not include connected apps." |
— |
Pro 플랜이 아닌 워크스페이스에 Claude 또는 ChatGPT를 연결함. |
업그레이드하거나 연결 화면에서 다른 워크스페이스를 선택하세요. |
| 시크릿 다시 생성이 업그레이드 대화 상자를 엶 |
— |
Pro 플랜이 아니면 시크릿을 다시 생성할 수 없음. |
Pro로 업그레이드하거나 토큰을 취소하세요. |
| "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로 업그레이드하세요. |
토큰에 {#access} 권한이 없음#
| 메시지 |
코드 |
원인 |
해결 방법 |
| "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.", "Choose 1080p, 2k or 4k.", "Exports are always 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 |
토큰당 일일 500MB |
| "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" |
귀하의 역할로는 웹훅을 관리할 수 없습니다. |
소유자나 관리자에게 문의하세요. |
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" (연결된 앱) |
앱의 로그인이 재사용되어 Clevera가 이를 취소했습니다. 앱을 다시 연결하세요. |
여전히 문제가 해결되지 않나요?#
오류에 포함된 request_id, 토큰 이름(토큰 값 자체는 제외), 호출 시간을 기재하여 고객 지원팀에 문의하세요.
