Коды ошибок REST API

Все ошибки REST API возвращают JSON вида:

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

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

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

HTTP	Сообщение	Причина	Что делать
400	text required	пустое поле в теле	проверить payload
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)	нет JWT	войти в кабинет повторно
401	Сессия истекла, войдите заново	JWT просрочен (7 дней)	повторный логин
403	Недостаточно прав: требуется scope "read"	нужен ключ с read	выпустить новый ключ
403	Недостаточно прав: требуется scope "write"	нужен ключ с write	—
403	Admins cannot create bots	админ не может иметь своих ботов	под пользовательской учёткой
404	Bot not found	бот не существует или принадлежит другому	проверить botId
404	Contact not found	контакта с таким external_user_id нет	—
404	Подписка не найдена	webhook подписка	—
409	Пользователь с таким email уже существует	при регистрации	—
409	Бот с таким ID/token уже добавлен	для одного провайдера токен уникален	удалите старый
429	Достигнут лимит активных ключей (20)	API tokens	отозвать старые
429	Достигнут лимит подписок (20)	webhook subscriptions	удалить ненужные

5xx — серверные

HTTP	Сообщение	Причина	Что делать
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)	нет — ошибка клиента, исправляйте payload
429	да, с задержкой Retry-After
502, 503, 504	да, с экспоненциальной задержкой (1с, 2с, 4с, 8с)
500	можно один раз, без зацикливания

Эндпоинт здоровья

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

{ "ok": true }

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