Коды ошибок открытого API

Все ошибки открытого API возвращают тело вида:

{ "message": "Описание ошибки" }

Код HTTP указывает класс ошибки.

4xx — ошибки клиента

Код	Сообщение	Причина	Что делать
400	text required	пустое поле в теле	проверить тело
400	text too long (max 4000 chars)	превышен лимит Telegram	сократить текст или разбить на несколько
400	userId and text required	/send без userId/text	заполнить оба поля
400	Personal send requires bot token	у бота не задан токен	добавить токен в кабинете
400	Broadcast requires bot token	то же для рассылки	—
400	kind must be photo, audio or file	неверный kind в multipart	использовать одно из трёх значений
400	platform must be all, tg or max	неверная платформа в /broadcast закрытого API	—
401	API-ключ обязателен	заголовок не пришёл	добавить X-API-Key
401	Неверный API-ключ	опечатка или удалён	проверить ключ
401	API-ключ отозван	вы или администратор его отозвали	выпустить новый
401	Срок действия API-ключа истёк	expires_at в прошлом	продлить или выпустить новый
401	Требуется авторизация (закрытый API)	нет сессии	войти в кабинет повторно
401	Сессия истекла, войдите заново	сессия просрочена (7 дней)	повторный вход
403	Недостаточно прав: требуется scope "read"	нужен ключ с read	выпустить новый ключ
403	Недостаточно прав: требуется scope "write"	нужен ключ с write	—
403	Admins cannot create bots	команда поддержки не может иметь своих ботов	войти под пользовательской учёткой
404	Bot not found	бот не существует или принадлежит другому	проверить идентификатор
404	Contact not found	контакта с таким external_user_id нет	—
404	Подписка не найдена	подписка на события	—
409	Пользователь с таким email уже существует	при регистрации	—
409	Бот с таким ID/token уже добавлен	для одной платформы токен уникален	удалите старого
429	Достигнут лимит активных ключей (20)	ключей API	отозвать старые
429	Достигнут лимит подписок (20)	подписок на события	удалить ненужные

5xx — ошибки сервера

Код	Сообщение	Причина	Что делать
500	Ошибка авторизации	внутренняя ошибка базы при проверке ключа	повторить через 5 секунд
500	без message	необработанное исключение	повторить, при повторе — в поддержку
502	Provider send failed	Telegram/Max ответил не-2xx	см. provider в теле для деталей
502	tg <code> или max <code>	сетевая ошибка к платформе	повторить

Пример 502 от Telegram:

{
  "message": "Provider send failed",
  "provider": {
    "ok": false,
    "error_code": 403,
    "description": "Forbidden: bot was blocked by the user"
  }
}

Стандартные ошибки Telegram (в provider)

error_code	Что значит
400	Bad Request — неверный chat_id, текст со сломанной разметкой
403	Forbidden — бот заблокирован пользователем или удалён из чата
404	Not Found — chat_id не существует
429	Too Many Requests — превышен лимит, ждать Retry-After секунд

Повторы

Класс ошибок	Стоит ли повторять
4xx (кроме 429)	нет — ошибка клиента, исправляйте тело запроса
429	да, с задержкой Retry-After
502, 503, 504	да, с увеличивающейся задержкой (1 с, 2 с, 4 с, 8 с)
500	можно один раз, без зацикливания

Метод проверки доступности

curl "https://app.maxbotstat.ru/health"

{ "ok": true }

Используйте для проверки доступности API в системе наблюдения.