Saltar al contenido
Centro de ayuda de Clevera

Solucionar errores de agentes de IA y API

Todos los mensajes que un agente de IA, script o persona puede ver con la API, el servidor MCP y la página de agentes de IA y API de Clevera, agrupados por causa: tokens, plan, permisos, trabajo pagado, límites de velocidad, conflictos y aplicaciones conectadas, junto con su solución.

Actualizado 10 min de lectura

Cuando Clevera rechaza la llamada de un agente, este recibe un código y un mensaje que indica qué hacer. Este artículo enumera todos los mensajes que un agente, script o persona puede ver en Agentes de IA y API, qué los causa y cómo solucionarlos. En la API REST, el código se encuentra en error.code; a través de MCP, el mismo mensaje se devuelve como un error de herramienta.

El token no es aceptado

Mensaje Código Causa Solución
"Send a Clevera agent token (Authorization: Bearer clv_agent_…) or connect through OAuth. Create a token in Integrations → AI agents & API." unauthenticated No se envió ningún token. Envía Authorization: Bearer <token>. Comprueba que CLEVERA_TOKEN esté configurado donde se ejecuta el agente.
"That is not a valid Clevera agent token. Create one in Integrations → AI agents & API." unauthenticated El valor está mal escrito, incompleto o no es un token de Clevera. Pega el token completo de nuevo.
"Unknown token. It may have been deleted; create a new one in Integrations → AI agents & API." unauthenticated Clevera no reconoce este token. Crea un token nuevo.
"OAuth connector tokens work on the MCP server only. Use a static token for the REST API." unauthenticated Se utilizó el inicio de sesión de una aplicación conectada en la API REST. Usa un token de API para REST.
"This token has expired. Create a new one in Integrations → AI agents & API." token_expired Su tiempo de vida ha finalizado. Crea un token nuevo.
"This token was revoked." token_revoked Alguien lo revocó, fue regenerado, su propietario se fue o Clevera lo revocó. Consulta por qué un token dejó de funcionar.
"The account that owns this token is suspended." token_revoked La cuenta del propietario está suspendida. Contacta con soporte.
"This token can't be used from this IP address." ip_not_allowed La llamada provino de fuera de la lista de permitidas de IP del token. Ejecuta el agente desde una dirección permitida o crea un token con la nueva dirección.

El plan no lo incluye

Agentes de IA y API (tokens, aplicaciones conectadas y webhooks) está disponible en los planes Pro, Business y Custom. En los planes Free y Starter, la página muestra "AI agents & API are included in Pro" con Actualizar a Pro. Al actualizar, los tokens, aplicaciones y webhooks existentes vuelven a funcionar; no se elimina nada.

Mensaje Código Causa Solución
"The agent API is not on this workspace's plan. It is on Pro and up." plan_locked (HTTP 403) El espacio de trabajo está en Free o Starter, o se cambió a uno de ellos. Se rechaza toda llamada de token y aplicación conectada. Actualizar a Pro. Los tokens que no hayan caducado volverán a funcionar.
Claude o ChatGPT solo dicen que no pudieron conectarse, o sus herramientas de Clevera fallan plan_locked en segundo plano El mismo rechazo de plan, mostrado por la aplicación como un error de conexión genérico. Actualiza el espacio de trabajo a Pro y vuelve a intentarlo en la aplicación.
"The API and agent access are not on your plan." — Crear un token o hacer clic en Aprobar en una solicitud de agente fuera de Pro. Actualizar a Pro. Denegar sigue funcionando.
"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 control bloqueado en Free o Starter. Actualizar a Pro.
workspace "(plan doesn’t include connected apps)" / "This workspace’s plan does not include connected apps." — Conectar Claude o ChatGPT a un espacio de trabajo fuera de Pro. Actualiza o elige otro espacio de trabajo en la pantalla de conexión.
Regenerar secreto abre el diálogo de actualización — Los secretos no se pueden regenerar fuera de Pro. Actualiza a Pro o revoca el token.
"Webhooks are not on your plan." — Enviar evento de prueba o Reenviar fuera de Pro. No se envía nada; los reintentos de espera terminan como fallidos con plan_locked. Actualizar a Pro.
"Your plan does not include paid agent work. Upgrade to let agents start it." plan_locked Trabajo pagado en un plan que no lo incluye. Actualizar a Pro.

El token no tiene permiso para

Mensaje Código Causa Solución
"This token lacks the ability ability. Ask the workspace member who owns it for a token that has it." forbidden_ability Al token le falta el permiso que requiere esta llamada. Crea un token con ese permiso. Consulta Permisos del agente.
"The token owner's current role in this workspace does not allow ability." forbidden_role El rol del propietario cambió desde que se creó el token. El token muestra Excede el rol. Alguien con el rol adecuado debe crear el token.
"Your role can’t grant some of these abilities." / "Your role can’t grant: abilities." — Crear un token con permisos que exceden tu rol. Desmárcalos o pídeselo a un propietario o administrador.
"You can't do this in this workspace." forbidden El rol o acceso del propietario no permite esta acción en este elemento. Comprueba el rol del propietario y el acceso a la colección.
"The token owner can view this article but not edit it (collection access)." forbidden_item El elemento está en una colección que el propietario solo puede ver. Dale al propietario acceso de edición a la colección.
"No item with that id in this token's scope. List or search first and use a returned id." not_found ID incorrecto, o el elemento está fuera de los sitios del token o del acceso del propietario. Enumera o busca, luego usa un ID devuelto.
"This content is live on a published site, so changing it needs the site:publish ability." live_content_needs_publish Editar (o traducir) un artículo de un sitio de documentación en vivo sin derechos de publicación. Dale al token site:publish o permite que se envíe para revisión.
"This article is also shown on a site this token cannot change. …" shared_outside_scope El artículo aparece en un sitio fuera de los sitios del token. Usa un token que cubra todos los sitios donde aparece o deja una nota de revisión.
"This site is paused or offline and read-only. A workspace owner can re-activate it in Docs." site_paused El sitio de documentación está pausado. Reactiva el sitio.
Mensaje Código Causa Solución
"This would pass the token's spend cap. A workspace admin can raise it." cap_exceeded El presupuesto no se ajusta al límite Por trabajo, Por día o Por mes del token. Espera al día o mes siguiente, o crea un token con límites más altos.
Un mensaje sobre el agotamiento de créditos insufficient_credits El espacio de trabajo no tiene suficientes créditos. Compra créditos o espera a la asignación.
"Your workspace cannot spend credits right now." plan_locked La facturación bloquea el gasto, por ejemplo, hay un pago pendiente. Revisa la Facturación.
"This quote has expired. Ask for a new quote." quote_expired Los presupuestos duran 15 minutos. Solicita un presupuesto nuevo.
"This quote was already used. Ask for a new quote." quote_used Un presupuesto inicia un trabajo. Solicita un presupuesto nuevo.
"This quote is for another kind of job." quote_mismatch Se usó un presupuesto de video para iniciar un clip, por ejemplo. Usa la llamada de inicio correspondiente.
"Another start is being checked. Try again in a moment." busy Dos inicios al mismo tiempo. Vuelve a intentarlo en un momento.
El trabajo espera con needs_input — Está esperando aprobación en Solicitudes del agente. Un propietario o administrador lo aprueba o deniega en un plazo de 24 horas.
El trabajo termina expired — Nadie tomó una decisión en 24 horas. Empieza de nuevo y apruébalo.
"This job can no longer be canceled." not_cancelable El trabajo ya terminó o ya no se puede cancelar. —

Mensajes de entrada comunes al solicitar videos: "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."

Demasiadas solicitudes

Mensaje Código Límite
"This token is over its request rate. Wait and retry." rate_limited 300 solicitudes por minuto por token
"This workspace is over its agent request rate. Wait and retry." rate_limited 1,200 por minuto por espacio de trabajo
"Too many writes from this token. Wait and retry." rate_limited 60 escrituras por minuto por token
"This token reached its daily write limit. Try again tomorrow." rate_limited 2,000 escrituras al día por token
"This token reached its hourly publish limit. Try again later." rate_limited 10 publicaciones por hora por token
"Too many uploads from this token. Wait and retry." rate_limited 30 subidas por minuto
"This token reached its daily upload volume. Try again tomorrow." rate_limited 500 MB al día por token
"Writes from this token are paused after an unusual burst of changes. The workspace owner was notified." rate_limited Actividad inusual: las escrituras se pausan durante 10 minutos
"Too many requests. Wait and retry." rate_limited 60 por minuto por dirección IP sin un token válido

Los inicios de pago también están limitados a 20 por hora por token y 100 al día por espacio de trabajo. Cada 429 tiene un encabezado Retry-After; espera ese tiempo.

Contenido y reintentos

Mensaje Código Solución
"The content changed since you read it. Re-read it …, merge your change and retry with that id." revision_conflict El agente vuelve a leer la página y aplica de nuevo su cambio.
"This idempotency key was used for a different request." idempotency_conflict / idempotency_key_reused Usa un Idempotency-Key nuevo para una solicitud nueva.
— idempotency_in_progress La primera solicitud con esta clave sigue en curso. Espera y luego reintenta con la misma clave.

Tokens y la página

Situación Causa Solución
Nuevo token está desactivado "Your workspace has reached its limit of 50 active tokens. Revoke one first." Revoca un token que no utilices.
No aparece la opción Regenerar secreto Solo el creador del token puede regenerarlo, y solo una vez. "Only the person who created this token can regenerate it. You can revoke it." Regenera el token más reciente o crea uno nuevo.
"This token was already regenerated, revoked or has expired; use its replacement or create a new one." El secreto ya se regeneró anteriormente. Usa el token de reemplazo.
No ves el token de un compañero Solo los propietarios y administradores ven todos los tokens. Pregunta a un propietario o administrador.
No puedes aprobar una solicitud: "An owner or admin decides" Solo los propietarios y administradores aprueban los gastos. Pregunta a un propietario o administrador.
"Only owners and admins manage webhooks" Tu rol no puede gestionar webhooks. Pregunta a un propietario o administrador.

Conectar Claude o ChatGPT

En pantalla Solución
"This request expired" "Too much time passed since the app asked. Start connecting again from the app."
"This app isn’t registered" Elimina el conector en la aplicación y añádelo de nuevo.
"This request can’t be trusted" "Nothing was shared. Start connecting again from the app." No conectes si sigue ocurriendo.
"Choose a workspace you are a member of." Elige uno de tus espacios de trabajo.
"Revoked: token reuse detected" en una aplicación conectada Se reutilizó el inicio de sesión de la aplicación, por lo que Clevera lo revocó. Conecta la aplicación de nuevo.

Sigues bloqueado

Contacta con soporte técnico indicando el request_id del error, el nombre del token (nunca el token en sí) y la hora de la llamada.

Gestionar tokens de APIPor qué un token dejó de funcionar.Permisos de agenteQué permiso necesita una llamada.Controlar gastos y aprobaciones de agentesLímites, cuotas y aprobaciones.Usar la API RESTFormato de error y límites de tasa.