Ошибки, лимиты и диагностика API

HTTP-статус показывает тип проблемы, а error.code — конкретную причину. Ошибку прав нужно исправить, конфликт версии — перечитать, а лимит — переждать. Не повторяйте любой неуспешный запрос одинаково.

Формат ошибки

json

{
  "error": {
    "code": "revision_conflict",
    "message": "Отчёт изменился после чтения",
    "details": {
      "expected_revision": 3,
      "revision": 5
    }
  }
}

Обязательны error.code и error.message. details уточняет параметры, недоступный блок или текущую версию. Ищите request_id внутри ошибки, а также в заголовке X-Request-Id.

Коды и действия

401unauthorized. Проверьте Bearer-заголовок. Ключ отсутствует, отозван или истёк. При необходимости создайте новый.

403forbidden_scope. Не хватает права для метода. Повтор прежнего запроса не поможет. Создайте ключ с нужными правами.

403tariff_expired / projects_limit_exceeded. Продлите тариф или приведите количество проектов к лимиту. Ссылка оплаты может быть в details.payment_url.

403block_forbidden. Включаемый блок недоступен аккаунту или тарифу. Не повторяйте включение без изменения условий.

403history_forbidden. История отчётов недоступна на тарифе. Повтор не поможет: смените тариф по ссылке из details.payment_url. Последний отчёт проекта есть в previous_report настроек генерации.

404not_found. Проверьте идентификатор и владельца ключа. Объект чужого аккаунта не открывается передачей другого user_id.

409revision_conflict. Перечитайте отчёт, сравните изменения и согласуйте повтор правки. Не подставляйте новую revision вслепую.

409report_not_ready. Дождитесь ready перед чтением блока, правкой или экспортом.

409report_busy. Подождите несколько секунд: отчёт занят другой операцией. Это не конфликт revision.

409source_unavailable. Доступ к источнику потерян. Если аккаунт источника отключили в «Аккаунтах», поле source проекта принимает значение unknown. Восстановите доступ к источнику в кабинете. Ссылка может быть в details.accounts_url.

422validation_failed. Исправьте параметры, даты, состав блоков или значения настроек. Подробности перечислены в details.

429rate_limited. Выдержите паузу Retry-After, затем повторите.

503queue_unavailable / export_failed. Недоступна очередь или сборка файла. Используйте ограниченные повторы с паузами.

500internal_error. Сохраните Request ID. При повторении ошибки передайте его поддержке вместе со временем и методом.

Лимиты запросов

На один ключ	Лимит
Все запросы	120 в минуту
Генерация и экспорт вместе	10 в минуту. Учитываются и в общем лимите.

X-RateLimit-Limit и X-RateLimit-Remaining показывают лимит и остаток. Для тяжёлого метода они отражают более строгий лимит. При 429 заголовок Retry-After задаёт паузу в секундах. Ограничения учитываются по ключу в минутных окнах.

text

HTTP/1.1 429 Too Many Requests
Retry-After: 12
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 0

Безопасные повторы

GET можно повторять при временной сетевой ошибке или недоступности, соблюдая паузы.
Повтор генерации с теми же параметрами обычно возвращает тот же отчёт. Проверяйте известный report_id. Для простого повтора refresh не нужен.
Не повторяйте refresh: true автоматически после неопределённого ответа: сначала проверьте состояние отчёта.
После потерянного ответа PUT перечитайте карточку и revision: запись могла состояться.
На revision_conflict не выполняйте слепой повтор с новой версией.
Для 500/503 ограничивайте число повторов и увеличивайте паузы. При 429 используйте Retry-After.

Предупреждения и failed

HTTP 200 не гарантирует успешную сборку. При status: failed читайте error_code. Даже при ready проверяйте warnings.

Предупреждение	Значение
`source_disconnected`	Источник отключён, данные могут отсутствовать.
`token_expired`	Истёк доступ к источнику аналитики, не персональный ключ API.
`report_broken`	Сборка содержит ошибки, проверьте полноту.
`no_previous_settings`	Нет предыдущего отчёта, использованы настройки по умолчанию.
`auto_settings_used`	Параметры взяты из автогенерации.

Диагностика в кабинете

Откройте «API & MCP» → Статистика. Проверьте активность ключа и журнал последних запросов: HTTP-статус, код ошибки, время и длительность. X-Request-Id из ответа помогает сопоставить запрос с журналом.

Вкладка Статистика: последние 50 запросов — время, ключ, метод и путь, проект, HTTP-статус и длительность. При наведении на время показывается Request ID.

В поддержку передавайте время, метод и путь запроса, Request ID и тело ошибки. Ключ и полный заголовок Authorization не отправляйте. Владельца и права можно проверить через GET /api/me.

Помогла статья?

← ПредыдущаяВебхуки о готовности и изменениях отчёта

← В категорию «API & MCP»В справочный центр