Limits and errors

Plan requirements, rate limits and the errors you may meet (401, 403, 404, 422, 429 and more), with what to do about each.

Which plan do I need? #

API access. The API and MCP need a plan with API access. Admins have it. Free accounts see the Settings page with an upgrade note.
Project Pro. The Project Pro pass (also part of every paid plan) opens the API and MCP for your project pages, your own Newsroom and Market only: the discover_* tools, list_market_listings, create_market_listing, update_market_listing, pause_market_listing, the change requests of Market and whoami. Tokens can then carry only read:products, write:products, read:market and write:market. SEO, Tag Manager, Media drafts and Content Autopilot need API access (Pro and above).
Search Console and GA4 data. Reading these needs the plan feature for search insights, and the Google connection set up in your Workspace.
Tag Manager changes. Reading Tag Manager uses the same plan feature as Search Console. Making changes needs the Tag Manager feature (part of the Pro plan and above).
Keywords. Daily lookups, tracked keywords and rank-check frequency depend on your plan, and free accounts have none. whoami shows what is left.
Uptime and reports. uptime_status and list_reports return empty lists when your plan lacks the feature.

Rate limits #

Limits apply per token: 60 requests a minute for reads and 20 a minute for writes (Tag Manager and Discover changes). If you go over, you get 429 and a Retry-After header with the seconds to wait.

Google Tag Manager has its own quota across the platform. If it is tight, a read or change may answer with a queued status and a change_id. Poll gtm_change_status to see when it is done.

The error format #

Errors come as JSON:

json

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

Read the code. It is stable.

Common errors #

HTTP	Meaning	What to do
401 `unauthenticated`	Token missing, wrong, expired or revoked.	Check the `Authorization: Bearer` header. Create a new token if needed.
403 `insufficient_scope`	The token lacks the scope.	Create a token with the scope (see Get a token).
403 `plan_required`	Your plan has no API access or this feature.	Check your plan.
404	Not found, or not yours.	Check the site host, slug or id. Another person's data always looks like 404.
404 `google_analytics_not_connected`	No GA4 property chosen for that site.	Choose one in SEO → Integrations.
409 `google_reconnect`	Your Google connection must be renewed.	Reconnect Google in the Workspace.
409 `translation_live`	You tried to edit a published language through the agent.	Edit it in Languages in the Workspace.
409 `busy`	Another request on the same thing is running.	Retry in a moment.
422	Validation failed, or `action_failed` when a change ran and failed.	Read the message. It uses the editor's wording.
429 `rate_limited`	Too many requests.	Wait for `Retry-After`.

Other codes you may see:

google_scope_missing: a Google permission is missing for a change that would run now. A proposal or confirmation still works. Grant it in your Google connection.
invalid_url: a screenshot address was not a public https image.
quota_reached: a limit of your plan is used: the monthly or daily Newsroom Brief quota, the active Market listings your plan holds, or the cap on new content (Project Pro: 30 a month and 5 a day for Briefs, new listings and page change requests together, web and MCP).
limit_reached (429): your plan's keyword limit is used. account_spend_cap (429): your account reached this month's keyword data limit.
provider_budget_reached (503): keyword data is paused for everyone for now. provider_not_connected (503) and provider_error (502) mean the data source is unavailable. Try later.
search_console_not_connected and gtm_not_connected (404): connect Search Console or Google Tag Manager in the Workspace under SEO, Integrations.
publish_cap_reached: the daily cap of automatic Tag Manager publishes is used; the owner confirms the publish instead.

202 is not an error #

Change tools answer 200 when done and 202 when the change is a proposal, waits for your confirmation (with confirm_url) or is queued. See Modes and approvals.

Pagination #

List endpoints return data and meta. Pass meta.next_cursor as cursor to get the next page.

If you are stuck #

Ask your assistant to call whoami. It shows your plan, remaining limits and the token's scopes, which explains most 403s.