Vai al contenuto
Centro assistenza Clevera

Risolvere gli errori dell'agente AI e dell'API

Ogni messaggio che un agente AI, uno script o una persona potrebbe visualizzare con l'API, il server MCP e la pagina Agenti AI & API di Clevera, raggruppati per causa: token, piano, autorizzazioni, lavoro a pagamento, limiti di frequenza, conflitti e app collegate, con la relativa soluzione.

Aggiornato 10 min di lettura

Quando Clevera rifiuta la chiamata di un agente, l'agente riceve un codice e un messaggio che indica cosa fare. Questo articolo elenca ogni messaggio che un agente, uno script o una persona potrebbe visualizzare con Agenti AI & API, la causa e come risolverlo. Tramite l'API REST, il codice si trova in error.code; tramite MCP, lo stesso messaggio viene restituito come errore dello strumento.

Il token non è accettato

Messaggio Codice Causa Soluzione
"Send a Clevera agent token (Authorization: Bearer clv_agent_…) or connect through OAuth. Create a token in Integrations → AI agents & API." unauthenticated Nessun token inviato. Invia Authorization: Bearer <token>. Verifica che CLEVERA_TOKEN sia impostato dove viene eseguito l'agente.
"That is not a valid Clevera agent token. Create one in Integrations → AI agents & API." unauthenticated Il valore è scritto male, troncato o non è un token Clevera. Incolla di nuovo l'intero token.
"Unknown token. It may have been deleted; create a new one in Integrations → AI agents & API." unauthenticated Clevera non riconosce questo token. Crea un nuovo token.
"OAuth connector tokens work on the MCP server only. Use a static token for the REST API." unauthenticated È stato utilizzato l'accesso di un'app collegata sull'API REST. Usa un token API per REST.
"This token has expired. Create a new one in Integrations → AI agents & API." token_expired La sua durata è terminata. Crea un nuovo token.
"This token was revoked." token_revoked Qualcuno lo ha revocato, è stato rigenerato, il proprietario ha lasciato l'azienda o Clevera lo ha revocato. Vedi perché un token ha smesso di funzionare.
"The account that owns this token is suspended." token_revoked L'account del proprietario è sospeso. Contatta l'assistenza.
"This token can't be used from this IP address." ip_not_allowed La chiamata proviene dall'esterno dell'elenco IP consentiti del token. Esegui l'agente da un indirizzo consentito o crea un token con il nuovo indirizzo.

Il piano non lo include

Agenti AI & API (token, app collegate e webhook) sono inclusi nei piani Pro, Business e Custom. Nei piani Free e Starter, la pagina mostra "AI agents & API are included in Pro" con <b>Passa a Pro</b>. L'aggiornamento riattiva i token, le app e i webhook esistenti; nulla viene eliminato.

Messaggio Codice Causa Soluzione
"The agent API is not on this workspace's plan. It is on Pro and up." plan_locked (HTTP 403) Lo spazio di lavoro è Free o Starter, o è stato spostato su uno di essi. Ogni chiamata di token e app collegata viene rifiutata. Passa a Pro. I token non scaduti funzioneranno di nuovo.
Claude o ChatGPT dicono solo che non è stato possibile connettersi, o i loro strumenti Clevera falliscono plan_locked dietro le quinte Lo stesso rifiuto del piano, mostrato dall'app come errore di connessione generico. Aggiorna lo spazio di lavoro a Pro, quindi riprova nell'app.
"The API and agent access are not on your plan." — Creazione di un token o clic su <b>Approva</b> su una richiesta dell'agente, fuori dal piano Pro. Passa a Pro. <b>Nega</b> continua a funzionare.
"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." — Un controllo bloccato su Free o Starter. Passa a Pro.
workspace "(plan doesn’t include connected apps)" / "This workspace’s plan does not include connected apps." — Connessione di Claude o ChatGPT a uno spazio di lavoro non Pro. Aggiorna o scegli un altro spazio di lavoro nella schermata di connessione.
<b>Rigenera segreto</b> apre la finestra di aggiornamento — I segreti non possono essere rigenerati fuori dal piano Pro. Passa a Pro o revoca il token.
"Webhooks are not on your plan." — <b>Invia evento di test</b> o <b>Riconsegna</b> fuori dal piano Pro. Nulla viene inviato; i tentativi in attesa terminano come falliti con plan_locked. Passa a Pro.
"Your plan does not include paid agent work. Upgrade to let agents start it." plan_locked Lavoro a pagamento su un piano che non lo include. Passa a Pro.

Il token non è autorizzato a

Messaggio Codice Causa Soluzione
"This token lacks the ability ability. Ask the workspace member who owns it for a token that has it." forbidden_ability Al token manca l'autorizzazione necessaria per questa chiamata. Crea un token con tale autorizzazione. Vedi Autorizzazioni dell'agente.
"The token owner's current role in this workspace does not allow ability." forbidden_role Il ruolo del proprietario è cambiato dopo la creazione del token. Il token mostra <b>Supera il ruolo</b>. Qualcuno con il ruolo corretto crea il token.
"Your role can’t grant some of these abilities." / "Your role can’t grant: abilities." — Creazione di un token con autorizzazioni superiori al tuo ruolo. Deselezionale o chiedi a un proprietario o amministratore.
"You can't do this in this workspace." forbidden Il ruolo o l'accesso del proprietario non consentono questa azione su questo elemento. Controlla il ruolo del proprietario e l'accesso alla raccolta.
"The token owner can view this article but not edit it (collection access)." forbidden_item L'elemento si trova in una raccolta che il proprietario può solo visualizzare. Concedi al proprietario l'accesso in modifica alla raccolta.
"No item with that id in this token's scope. List or search first and use a returned id." not_found ID errato o l'elemento è fuori dai siti del token o dall'accesso del proprietario. Elenca o cerca, quindi usa un ID restituito.
"This content is live on a published site, so changing it needs the site:publish ability." live_content_needs_publish Modifica (o traduzione) di un articolo di un sito di documentazione live senza diritti di pubblicazione. Concedi al token site:publish o lascialo inviare per la revisione.
"This article is also shown on a site this token cannot change. …" shared_outside_scope L'articolo appare su un sito al di fuori dei siti del token. Usa un token che copra ogni sito in cui viene mostrato o lascia una nota di revisione.
"This site is paused or offline and read-only. A workspace owner can re-activate it in Docs." site_paused Il sito di documentazione è in pausa. Riattiva il sito.
Messaggio Codice Causa Soluzione
"This would pass the token's spend cap. A workspace admin can raise it." cap_exceeded Il preventivo supera il limite <b>Per attività</b>, <b>Al giorno</b> o <b>Al mese</b> del token. Attendi il giorno o il mese successivo, o crea un token con limiti più alti.
Un messaggio sull'esaurimento dei crediti insufficient_credits Lo spazio di lavoro non ha abbastanza crediti. Acquista crediti o attendi l'assegnazione.
"Your workspace cannot spend credits right now." plan_locked La fatturazione blocca la spesa, ad esempio è dovuto un pagamento. Controlla <b>Fatturazione</b>.
"This quote has expired. Ask for a new quote." quote_expired I preventivi durano 15 minuti. Chiedi un nuovo preventivo.
"This quote was already used. Ask for a new quote." quote_used Un preventivo avvia un'attività. Chiedi un nuovo preventivo.
"This quote is for another kind of job." quote_mismatch È stato usato un preventivo video per avviare una clip, ad esempio. Usa la chiamata di avvio corrispondente.
"Another start is being checked. Try again in a moment." busy Due avvii nello stesso momento. Riprova dopo un secondo.
L'attività attende con needs_input — È in attesa di approvazione su <b>Richieste dell'agente</b>. Un proprietario o amministratore approva o nega entro 24 ore.
L'attività termina expired — Nessuno ha deciso entro 24 ore. Ricomincia e approvala.
"This job can no longer be canceled." not_cancelable L'attività è già terminata o è oltre il punto di annullamento. —

Messaggi di input comuni quando si richiedono video: "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."

Troppe richieste

Messaggio Codice Limite
"This token is over its request rate. Wait and retry." rate_limited 300 richieste al minuto per token
"This workspace is over its agent request rate. Wait and retry." rate_limited 1.200 al minuto per spazio di lavoro
"Too many writes from this token. Wait and retry." rate_limited 60 scritture al minuto per token
"This token reached its daily write limit. Try again tomorrow." rate_limited 2.000 scritture al giorno per token
"This token reached its hourly publish limit. Try again later." rate_limited 10 pubblicazioni all'ora per token
"Too many uploads from this token. Wait and retry." rate_limited 30 caricamenti al minuto
"This token reached its daily upload volume. Try again tomorrow." rate_limited 500 MB al giorno per token
"Writes from this token are paused after an unusual burst of changes. The workspace owner was notified." rate_limited Attività insolita: le scritture si interrompono per 10 minuti
"Too many requests. Wait and retry." rate_limited 60 al minuto per indirizzo IP senza un token valido

Gli avvii a pagamento sono inoltre limitati a 20 all'ora per token e 100 al giorno per area di lavoro. Ogni 429 ha un'intestazione Retry-After; attendi quel tempo.

Contenuto e nuovi tentativi

Messaggio Codice Soluzione
"The content changed since you read it. Re-read it …, merge your change and retry with that id." revision_conflict L'agente rilegge la pagina e riapplica la modifica.
"This idempotency key was used for a different request." idempotency_conflict / idempotency_key_reused Usa un nuovo Idempotency-Key per una nuova richiesta.
— idempotency_in_progress La prima richiesta con questa chiave è ancora in esecuzione. Attendi, quindi riprova con la stessa chiave.

Token e pagina

Situazione Causa Soluzione
Nuovo token è disabilitato "Your workspace has reached its limit of 50 active tokens. Revoke one first." Revoca un token che non utilizzi.
Nessuna opzione Rigenera segreto Solo il creatore del token può rigenerarlo, e solo una volta. "Only the person who created this token can regenerate it. You can revoke it." Rigenera il token più recente o creane uno.
"This token was already regenerated, revoked or has expired; use its replacement or create a new one." Il segreto è già stato rigenerato in precedenza. Usa il token sostitutivo.
Non vedi il token di un collega Solo proprietari e amministratori vedono ogni token. Chiedi a un proprietario o a un amministratore.
Non puoi approvare una richiesta: "An owner or admin decides" Solo proprietari e amministratori approvano la spesa. Chiedi a un proprietario o a un amministratore.
"Only owners and admins manage webhooks" Il tuo ruolo non può gestire i webhook. Chiedi a un proprietario o a un amministratore.

Connessione di Claude o ChatGPT

A schermo Soluzione
"This request expired" "Too much time passed since the app asked. Start connecting again from the app."
"This app isn’t registered" Rimuovi il connettore nell'app e aggiungilo di nuovo.
"This request can’t be trusted" "Nothing was shared. Start connecting again from the app." Non connetterti se il problema persiste.
"Choose a workspace you are a member of." Scegli una delle tue aree di lavoro.
"Revoked: token reuse detected" su un'app connessa L'accesso dell'app è stato riutilizzato, quindi Clevera lo ha revocato. Connetti di nuovo l'app.

Ancora bloccato

Contatta l'assistenza con il request_id dell'errore, il nome del token (mai il token stesso) e l'orario della chiamata.

Gestisci i token APIPerché un token ha smesso di funzionare.Autorizzazioni dell'agenteQuale autorizzazione richiede una chiamata.Controlla la spesa e le approvazioni dell'agenteLimiti, quote e approvazioni.Usa la REST APIFormato dell'errore e limiti di frequenza.