Ліміти й помилки

Які потрібні тарифи, ліміти запитів і помилки, які можуть трапитися (401, 403, 404, 422, 429 та інші), і що робити в кожному випадку.

Який тариф потрібен? #

Доступ до API. Для API та MCP потрібен тариф із доступом до API. Адміністратори його мають. Безплатні акаунти бачать сторінку налаштувань із пропозицією оновити тариф.
Project Pro. Пас Project Pro (входить і в кожен платний тариф) відкриває API та MCP лише для сторінок вашого проєкту, власного Newsroom і Market: інструменти discover_*, list_market_listings, create_market_listing, update_market_listing, pause_market_listing, запити на зміни Market і whoami. Тоді токени матимуть лише read:products, write:products, read:market і write:market. SEO, Tag Manager, чернетки Media і Content Autopilot потребують доступу до API (Pro і вище).
Дані Search Console і GA4. Для читання потрібна функція тарифу «search insights» і налаштоване підключення Google у Workspace.
Зміни в Tag Manager. Читання Tag Manager потребує тієї самої функції, що й Search Console. Для змін потрібна функція Tag Manager (входить у тариф Pro і вищі).
Ключові слова. Денні пошуки, відстежувані слова й частота перевірок позицій залежать від тарифу, а на безплатних акаунтах їх немає. Залишок покаже whoami.
Аптайм і звіти. uptime_status і list_reports повертають порожні списки, якщо функції немає на вашому тарифі.

Ліміти запитів #

Ліміти діють на кожен токен: 60 запитів на хвилину на читання й 20 на хвилину на запис (зміни в Tag Manager і Discover). Якщо перевищите, отримаєте 429 і заголовок Retry-After із кількістю секунд очікування.

У Google Tag Manager є власна квота на всю платформу. Коли вона вичерпується, читання чи зміна можуть відповісти статусом queued з change_id. Перевіряйте готовність через gtm_change_status.

Формат помилок #

Помилки приходять у JSON:

json

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

Дивіться на code. Він стабільний.

Поширені помилки #

HTTP	Що означає	Що робити
401 `unauthenticated`	Токена немає, він хибний, прострочений або відкликаний.	Перевірте заголовок `Authorization: Bearer`. За потреби створіть новий токен.
403 `insufficient_scope`	У токена немає потрібного scope.	Створіть токен зі scope (див. Отримайте токен).
403 `plan_required`	Ваш тариф без доступу до API чи цієї функції.	Перевірте тариф.
404	Не знайдено або це не ваше.	Перевірте хост сайту, slug чи id. Чужі дані завжди виглядають як 404.
404 `google_analytics_not_connected`	Для сайту не вибрано ресурс GA4.	Оберіть його в SEO → Integrations.
409 `google_reconnect`	Підключення Google треба оновити.	Підключіть Google заново у Workspace.
409 `translation_live`	Ви спробували змінити опубліковану мову через агента.	Редагуйте її в розділі Languages у Workspace.
409 `busy`	Інший запит до того самого об'єкта ще виконується.	Повторіть за мить.
422	Перевірка не пройдена, або `action_failed`, якщо зміна запустилася й завершилась невдало.	Прочитайте повідомлення: воно сформульоване так само, як у редакторі.
429 `rate_limited`	Забагато запитів.	Зачекайте за `Retry-After`.

Інші коди, які ви можете побачити:

google_scope_missing: бракує дозволу Google для зміни, що мала б виконатися одразу. Пропозиція чи підтвердження все одно працюють. Надайте дозвіл у підключенні Google.
invalid_url: адреса скріншота не є публічним https-зображенням.
quota_reached: вичерпано ліміт вашого тарифу: місячну чи денну квоту Brief у Newsroom, кількість активних оголошень Market або ліміт нового контенту (Project Pro: 30 на місяць і 5 на день для Brief, нових оголошень і запитів на зміну сторінок разом, у вебі та MCP).
limit_reached (429): вичерпано ліміт ключових слів вашого тарифу. account_spend_cap (429): акаунт досяг цьогомісячного ліміту даних про ключові слова.
provider_budget_reached (503): дані про ключові слова тимчасово призупинені для всіх. provider_not_connected (503) і provider_error (502) означають, що джерело даних недоступне. Спробуйте пізніше.
search_console_not_connected і gtm_not_connected (404): підключіть Search Console або Google Tag Manager у Workspace, розділ SEO, Integrations.
publish_cap_reached: денний ліміт автоматичних публікацій Tag Manager вичерпано; натомість публікацію підтверджує власник.

202 не є помилкою #

Інструменти змін відповідають 200, коли зміну виконано, і 202, коли це пропозиція, вона чекає на ваше підтвердження (з confirm_url) або стоїть у черзі. Див. Режими й підтвердження.

Пагінація #

Списки повертають data і meta. Передайте meta.next_cursor як cursor, щоб отримати наступну сторінку.

Якщо щось не виходить #

Попросіть асистента викликати whoami. Він покаже тариф, залишки лімітів і scopes токена, а це пояснює більшість помилок 403.