Ошибки

Как выглядит ошибка

Ответ об ошибке несёт человеческий текст и машинный код:

{
  "error": "у ключа нет права subscribers:write",
  "code": "forbidden_scope",
  "Error": "у ключа нет права subscribers:write"
}

• error — что случилось, словами. Можно показать пользователю.
• code — по нему ветвится код: он не меняется от версии к версии, в отличие от текста.
• Error — то же самое, что error. Оставлено для старых интеграций: раньше ошибка приходила именно в этом поле.

У методов первой очереди формат прежний

Каталог, календарь, прокси и другие методы первой очереди отвечают как раньше — полем Error без машинного кода. Ошибки авторизации и превышения частоты у них теперь приходят в новом формате, но со старым полем внутри.

---

Коды ответа

Код	Причина	Что проверить
401	Ошибка авторизации	Передан ли ключ: заголовок Authorization, X-Api-Key или параметр key. Не отозван ли ключ и не истёк ли его срок
403	Нет доступа	У ключа нет нужного права, либо аккаунт выключен, либо возможность не входит в тариф
404	Не найдено	Бот, подписчик, список, цепочка или строка с такими параметрами не существуют
409	Так нельзя	Действие противоречит состоянию: цепочка выключена, подписчик заблокировал бота, ключ идемпотентности переиспользован
422	Ошибка в параметре	Переданы ли все обязательные параметры метода. Сверьтесь со схемой запроса
429	Превышена частота	Не больше 10 запросов в секунду. Загляните в заголовок Retry-After
500, 502	Сбой на нашей стороне	Повторите позже. Если повторяется — напишите в поддержку и приложите время запроса

---

Машинные коды

Авторизация и права

code	Значение
unauthorized	ключ не передан или не найден
key_revoked	ключ отозван
key_expired	срок действия ключа истёк
forbidden_scope	у ключа нет нужного права
account_off	аккаунт выключен
rate_limit	слишком часто
tariff	возможность не входит в тариф

Параметры

code	Значение
no_botid, no_clientid	не указан бот или подписчик
no_bot, no_subscriber	бот или подписчик не найдены
many_bots	в аккаунте несколько ботов этого мессенджера — уточните botid
no_list, no_row	список или строка не найдены
no_chain, no_message, no_block	цепочка, шаг или блок не найдены
no_text, no_row, no_where, no_sum	не передано то, без чего метод бессмыслен
bad_scope, bad_event, bad_url	значение не из допустимого набора

Состояние

code	Значение
subscriber_off	подписчик отключён
subscriber_blocked	подписчик заблокировал бота
chain_off	цепочка выключена
chain_empty	в цепочке нет включённых шагов
not_scenario	шаг не сценарий, блоков в нём нет
no_active_chain	у подписчика нет запущенных цепочек — переменной негде жить
idempotency_conflict	тот же Idempotency-Key пришёл с другими параметрами
list_exists, stage_exists	такое название уже занято

---

Как обрабатывать

Стратегия в боте

В сценариях действий после вызова метода API сохраняйте JSON-ответ и HTTP-статус в переменные — это позволит ветвить логику по коду ошибки и показывать пользователю осмысленное сообщение вместо общей «что-то пошло не так».

Защита от 429

Не запускайте API-вызовы в цикле без задержек. Для массовых операций используйте методы, рассчитанные на пачку: /list/rows/add принимает до 500 строк за раз, /broadcast/send рассылает по сегменту одним запросом, а внутри бота есть массовые операции и Списки.

Повторяйте безопасно

Если запрос оборвался и вы не знаете, дошёл ли он, повторяйте с тем же заголовком Idempotency-Key — второй записи не появится. См. Авторизация.