Pular para o conteúdo
Central de Ajuda Clevera

Corrigir erros de agentes de IA e API

Todas as mensagens que um agente de IA, script ou pessoa pode ver com a API, servidor MCP e a página de agentes de IA e API da Clevera, agrupadas por causa: tokens, plano, permissões, trabalho pago, limites de taxa, conflitos e conexão de aplicativos, com a correção.

Atualizado 10 min de leitura

Quando a Clevera recusa a chamada de um agente, o agente recebe um código e uma mensagem que diz o que fazer. Este artigo lista todas as mensagens que um agente, script ou pessoa pode ver com Agentes de IA e API, o que as causa e como corrigi-las. Na API REST, o código está em error.code; no MCP, a mesma mensagem retorna como um erro de ferramenta.

O token não é aceito

Mensagem Código Causa Correção
"Send a Clevera agent token (Authorization: Bearer clv_agent_…) or connect through OAuth. Create a token in Integrations → AI agents & API." unauthenticated Nenhum token foi enviado. Envie Authorization: Bearer <token>. Verifique se CLEVERA_TOKEN está definido onde o agente é executado.
"That is not a valid Clevera agent token. Create one in Integrations → AI agents & API." unauthenticated O valor está digitado incorretamente, cortado ou não é um token da Clevera. Cole o token completo novamente.
"Unknown token. It may have been deleted; create a new one in Integrations → AI agents & API." unauthenticated A Clevera não reconhece este token. Crie um novo token.
"OAuth connector tokens work on the MCP server only. Use a static token for the REST API." unauthenticated O login de um aplicativo conectado foi usado na API REST. Use um token de API para REST.
"This token has expired. Create a new one in Integrations → AI agents & API." token_expired Sua vida útil expirou. Crie um novo token.
"This token was revoked." token_revoked Alguém o revogou, ele foi regenerado, seu proprietário saiu ou a Clevera o revogou. Veja por que um token parou de funcionar.
"The account that owns this token is suspended." token_revoked A conta do proprietário está suspensa. Entre em contato com o suporte.
"This token can't be used from this IP address." ip_not_allowed A chamada veio de fora da lista de permissões de IP do token. Execute o agente a partir de um endereço permitido ou crie um token com o novo endereço.

O plano não inclui isso

Agentes de IA e API (tokens, aplicativos conectados e webhooks) estão nos planos Pro, Business e Custom. Nos planos Free e Starter, a página mostra "AI agents & API are included in Pro" com Fazer upgrade para o Pro. Fazer o upgrade faz com que tokens, aplicativos e webhooks existentes voltem a funcionar; nada é excluído.

Mensagem Código Causa Correção
"The agent API is not on this workspace's plan. It is on Pro and up." plan_locked (HTTP 403) O workspace está no plano Free ou Starter, ou foi movido para um deles. Toda chamada de token e aplicativo conectado é recusada. Fazer upgrade para o Pro. Tokens que não expiraram voltam a funcionar.
Claude ou ChatGPT apenas diz que não conseguiu conectar, ou suas ferramentas Clevera falham plan_locked nos bastidores A mesma recusa de plano, mostrada pelo aplicativo como um erro genérico de conexão. Faça o upgrade do workspace para o Pro e tente novamente no aplicativo.
"The API and agent access are not on your plan." — Criar um token ou clicar em Aprovar em uma solicitação de agente, fora do Pro. Fazer upgrade para o Pro. Negar ainda funciona.
"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." — Um controle bloqueado no Free ou Starter. Fazer upgrade para o Pro.
workspace "(plan doesn’t include connected apps)" / "This workspace’s plan does not include connected apps." — Conectar Claude ou ChatGPT a um workspace fora do Pro. Faça o upgrade ou escolha outro workspace na tela de conexão.
Regenerar segredo abre a caixa de diálogo de upgrade — Segredos não podem ser regenerados fora do Pro. Fazer upgrade para o Pro ou revogar o token.
"Webhooks are not on your plan." — Enviar evento de teste ou Redeliver fora do Pro. Nada é enviado; as tentativas de espera terminam como falhas com plan_locked. Fazer upgrade para o Pro.
"Your plan does not include paid agent work. Upgrade to let agents start it." plan_locked Trabalho pago em um plano sem esse recurso. Fazer upgrade para o Pro.

O token não tem permissão para

Mensagem Código Causa Correção
"This token lacks the ability ability. Ask the workspace member who owns it for a token that has it." forbidden_ability O token não tem a permissão necessária para esta chamada. Crie um token com essa permissão. Veja Permissões do agente.
"The token owner's current role in this workspace does not allow ability." forbidden_role A função do proprietário mudou desde que o token foi criado. O token mostra Excede a função. Alguém com a função correta cria o token.
"Your role can’t grant some of these abilities." / "Your role can’t grant: abilities." — Criar um token com permissões além da sua função. Desmarque-as ou peça a um proprietário ou administrador.
"You can't do this in this workspace." forbidden A função ou acesso do proprietário não permite esta ação neste item. Verifique a função do proprietário e o acesso à coleção.
"The token owner can view this article but not edit it (collection access)." forbidden_item O item está em uma coleção que o proprietário só pode visualizar. Dê ao proprietário acesso de edição à coleção.
"No item with that id in this token's scope. List or search first and use a returned id." not_found ID incorreto ou o item está fora dos sites do token ou do acesso do proprietário. Liste ou pesquise e use um ID retornado.
"This content is live on a published site, so changing it needs the site:publish ability." live_content_needs_publish Editar (ou traduzir) um artigo de site de documentação ativo sem direitos de publicação. Dê ao token site:publish ou permita que ele envie para revisão.
"This article is also shown on a site this token cannot change. …" shared_outside_scope O artigo aparece em um site fora dos sites do token. Use um token que cubra todos os sites onde ele aparece ou deixe uma nota de revisão.
"This site is paused or offline and read-only. A workspace owner can re-activate it in Docs." site_paused O site de documentação está pausado. Reative o site.
Mensagem Código Causa Correção
"This would pass the token's spend cap. A workspace admin can raise it." cap_exceeded O orçamento não se encaixa no limite Por trabalho, Por dia ou Por mês do token. Aguarde o próximo dia ou mês, ou crie um token com limites maiores.
Uma mensagem sobre créditos acabando insufficient_credits O workspace não tem créditos suficientes. Compre créditos ou aguarde a renovação.
"Your workspace cannot spend credits right now." plan_locked O faturamento bloqueia gastos, por exemplo, um pagamento pendente. Verifique o Faturamento.
"This quote has expired. Ask for a new quote." quote_expired Orçamentos duram 15 minutos. Peça um novo orçamento.
"This quote was already used. Ask for a new quote." quote_used Um orçamento inicia um trabalho. Peça um novo orçamento.
"This quote is for another kind of job." quote_mismatch Um orçamento de vídeo foi usado para iniciar um clipe, por exemplo. Use a chamada de início correspondente.
"Another start is being checked. Try again in a moment." busy Dois inícios no mesmo momento. Tente novamente após um segundo.
O trabalho aguarda com needs_input — Está aguardando aprovação em Solicitações do agente. Um proprietário ou administrador aprova ou nega em até 24 horas.
O trabalho termina expired — Ninguém decidiu em 24 horas. Comece novamente e aprove.
"This job can no longer be canceled." not_cancelable O trabalho já terminou ou passou do ponto de cancelamento. —

Mensagens de entrada comuns ao solicitar vídeos: "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."

Muitas solicitações

Mensagem Código Limite
"This token is over its request rate. Wait and retry." rate_limited 300 solicitações por minuto por token
"This workspace is over its agent request rate. Wait and retry." rate_limited 1.200 por minuto por workspace
"Too many writes from this token. Wait and retry." rate_limited 60 gravações por minuto por token
"This token reached its daily write limit. Try again tomorrow." rate_limited 2.000 gravações por dia por token
"This token reached its hourly publish limit. Try again later." rate_limited 10 publicações por hora por token
"Too many uploads from this token. Wait and retry." rate_limited 30 uploads por minuto
"This token reached its daily upload volume. Try again tomorrow." rate_limited 500 MB por dia por token
"Writes from this token are paused after an unusual burst of changes. The workspace owner was notified." rate_limited Atividade incomum: gravações pausadas por 10 minutos
"Too many requests. Wait and retry." rate_limited 60 por minuto por endereço IP sem um token válido

Inícios pagos também são limitados a 20 por hora por token e 100 por dia por workspace. Cada 429 tem um cabeçalho Retry-After; aguarde esse tempo.

Conteúdo e novas tentativas

Mensagem Código Correção
"The content changed since you read it. Re-read it …, merge your change and retry with that id." revision_conflict O agente lê a página novamente e reaplica sua alteração.
"This idempotency key was used for a different request." idempotency_conflict / idempotency_key_reused Use um Idempotency-Key novo para uma nova solicitação.
— idempotency_in_progress A primeira solicitação com esta chave ainda está em execução. Aguarde e tente novamente com a mesma chave.

Tokens e a página

Situação Causa Correção
Novo token está desativado "Your workspace has reached its limit of 50 active tokens. Revoke one first." Revogue um token que você não usa.
Sem a opção Regenerar segredo Apenas o criador do token pode regenerá-lo, e apenas uma vez. "Only the person who created this token can regenerate it. You can revoke it." Regenere o token mais recente ou crie um.
"This token was already regenerated, revoked or has expired; use its replacement or create a new one." O segredo já foi regenerado anteriormente. Use o token de substituição.
Você não vê o token de um colega Apenas proprietários e administradores veem todos os tokens. Peça a um proprietário ou administrador.
Você não pode aprovar uma solicitação: "An owner or admin decides" Apenas proprietários e administradores aprovam gastos. Peça a um proprietário ou administrador.
"Only owners and admins manage webhooks" Sua função não pode gerenciar webhooks. Peça a um proprietário ou administrador.

Conectando Claude ou ChatGPT

Na tela Correção
"This request expired" "Too much time passed since the app asked. Start connecting again from the app."
"This app isn’t registered" Remova o conector no aplicativo e adicione-o novamente.
"This request can’t be trusted" "Nothing was shared. Start connecting again from the app." Não conecte se isso continuar acontecendo.
"Choose a workspace you are a member of." Escolha um de seus workspaces.
"Revoked: token reuse detected" em um aplicativo conectado O login do aplicativo foi reutilizado, então o Clevera o revogou. Conecte o aplicativo novamente.

Ainda com problemas

Entre em contato com o suporte com o request_id do erro, o nome do token (nunca o token em si) e o horário da chamada.

Gerenciar tokens de APIPor que um token parou de funcionar.Permissões do agenteQual permissão uma chamada precisa.Controlar gastos e aprovações do agenteLimites, cotas e aprovações.Usar a API RESTFormato de erro e limites de taxa.