Límites y errores

Requisitos de plan, límites de peticiones y los errores que puedes encontrar (401, 403, 404, 422, 429 y más), con qué hacer en cada caso.

¿Qué plan necesito? #

Acceso a la API. La API y el MCP necesitan un plan con acceso a la API. Los administradores lo tienen. Las cuentas gratuitas ven la página de ajustes con una invitación a mejorar.
Project Pro. El pase Project Pro (también incluido en cada plan de pago) abre la API y el MCP solo para las páginas de tu proyecto, tu propio Newsroom y Market: las herramientas discover_*, list_market_listings, create_market_listing, update_market_listing, pause_market_listing, las solicitudes de cambio de Market y whoami. Los tokens solo podrán llevar read:products, write:products, read:market y write:market. SEO, Tag Manager, borradores de Media y Content Autopilot necesitan acceso a la API (Pro y superior).
Datos de Search Console y GA4. Leerlos requiere la función de plan de search insights y la conexión con Google hecha en tu Workspace.
Cambios en Tag Manager. Leer Tag Manager usa la misma función de plan que Search Console. Hacer cambios requiere la función de Tag Manager (incluida en el plan Pro y superiores).
Palabras clave. Las consultas diarias, las palabras en seguimiento y la frecuencia de comprobación dependen del plan, y las cuentas gratuitas no tienen. whoami te dice lo que queda.
Uptime e informes. uptime_status y list_reports devuelven listas vacías si tu plan no incluye la función.

Límites de peticiones #

Los límites se aplican por token: 60 peticiones por minuto de lectura y 20 por minuto de escritura (cambios en Tag Manager y Discover). Si te pasas, recibes 429 y una cabecera Retry-After con los segundos que debes esperar.

Google Tag Manager tiene además su propia cuota para toda la plataforma. Si va justa, una lectura o un cambio puede responder con estado queued y un change_id. Consulta gtm_change_status para saber cuándo termina.

El formato de los errores #

Los errores llegan como JSON:

json

{ "error": { "code": "insufficient_scope", "message": "...", "details": {} } }

Fíjate en el code. Es estable.

Errores comunes #

HTTP	Significado	Qué hacer
401 `unauthenticated`	Falta el token, es incorrecto, ha caducado o está revocado.	Revisa la cabecera `Authorization: Bearer`. Crea un token nuevo si hace falta.
403 `insufficient_scope`	Al token le falta el scope.	Crea un token con el scope (mira Obtén un token).
403 `plan_required`	Tu plan no tiene acceso a la API o a esta función.	Revisa tu plan.
404	No existe, o no es tuyo.	Revisa el host del sitio, el slug o el id. Los datos de otra persona siempre parecen un 404.
404 `google_analytics_not_connected`	No hay propiedad de GA4 elegida para ese sitio.	Elige una en SEO → Integrations.
409 `google_reconnect`	Debes renovar tu conexión con Google.	Vuelve a conectar Google en el Workspace.
409 `translation_live`	Intentaste editar un idioma publicado a través del agente.	Edítalo en Languages dentro del Workspace.
409 `busy`	Hay otra petición en marcha sobre lo mismo.	Reintenta en un momento.
422	Falló la validación, o `action_failed` cuando un cambio se ejecutó y falló.	Lee el mensaje. Usa las mismas palabras que el editor.
429 `rate_limited`	Demasiadas peticiones.	Espera lo que diga `Retry-After`.

Otros códigos que puedes ver:

google_scope_missing: falta un permiso de Google para un cambio que se ejecutaría ahora. Una propuesta o una confirmación sí funcionan. Concédelo en tu conexión con Google.
invalid_url: la dirección de la captura no era una imagen https pública.
quota_reached: se agotó un límite de tu plan: la cuota mensual o diaria de Briefs de Newsroom, los anuncios activos de Market que admite tu plan o el tope de contenido nuevo (Project Pro: 30 al mes y 5 al día para Briefs, anuncios nuevos y cambios de página juntos, en la web y por MCP).
limit_reached (429): has agotado el límite de palabras clave de tu plan. account_spend_cap (429): tu cuenta llegó al límite de datos de palabras clave de este mes.
provider_budget_reached (503): los datos de palabras clave están en pausa para todos por ahora. provider_not_connected (503) y provider_error (502) significan que la fuente de datos no está disponible. Inténtalo más tarde.
search_console_not_connected y gtm_not_connected (404): conecta Search Console o Google Tag Manager en el Workspace, en SEO, Integrations.
publish_cap_reached: se ha agotado el límite diario de publicaciones automáticas de Tag Manager; en su lugar, el propietario confirma la publicación.

Un 202 no es un error #

Las herramientas de cambio responden 200 cuando está hecho y 202 cuando el cambio es una propuesta, espera tu confirmación (con confirm_url) o está en cola. Mira Modos y aprobaciones.

Paginación #

Los endpoints de lista devuelven data y meta. Pasa meta.next_cursor como cursor para pedir la página siguiente.

Si te atascas #

Pide a tu asistente que llame a whoami. Muestra tu plan, los límites que quedan y los scopes del token, lo que explica la mayoría de los 403.