Как подключиться к API MAX: токен, первый запрос и таблица ошибок

Вечер, документация открыта во второй вкладке, токен бота скопирован, и первый запрос к API MAX возвращается с кодом 401, хотя только что все выглядело безупречно. За годы в корпоративном ИТ и внутреннем аудите я привыкла читать ответ сервера так же, как акт проверки: сначала код, потом формулировку, и только потом выводы о том, кто виноват.

В этой статье разбираю путь от токена до бота, который принимает и отправляет сообщения, и отдаю таблицу ошибок, которую удобно держать рядом с журналом ответов, чтобы по коду сразу понимать, куда смотреть.

Где взять токен и как его хранить

Токен выдаётся при создании бота на платформе MAX для партнёров, и порядок получения вместе с требованиями к владельцу бота описан в официальной документации MAX для разработчиков, которую я советую открыть до первой строки кода. Документация обновляется, поэтому любые пересказы, включая мой, сверяйте с ней.

Токен работает как ключ от бота целиком: кто им владеет, тот пишет от имени бота, читает входящие и меняет подписки на события. Поэтому его место в переменной окружения или в хранилище секретов, и уж точно не в репозитории, где его рано или поздно увидит кто-то лишний.

Если токен утёк, его перевыпускают, и здесь кроется частая причина ошибки 401: новый токен уже выдан, а старый ещё лежит в конфиге тестового сервера, в переменных сборки или в скрипте, который коллега запускает по расписанию и о котором все забыли.

Путь от токена до рабочего бота

Подключение удобно проходить ступенями, где каждая следующая опирается на проверенную предыдущую, потому что ошибку, пойманную на первой ступени, чинят быстро, а ту же ошибку, всплывшую в рабочем боте при живых пользователях, ищут по журналам долго и с нервами.

Порядок у меня всегда один и тот же: токен в хранилище и проверка через метод сведений о боте → одно сообщение самому себе → приём событий → вебхук → журнал и повторы. Перескакивать через ступени соблазнительно, но тогда при первой же ошибке вы не знаете, на каком из этажей она живет.

Первый запрос: проверяю, что бот жив

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

Запрос собирается из нескольких частей, и каждая может сломаться отдельно, поэтому я проверяю их по очереди, прежде чем подозревать сервис:

Адрес: сервер, указанный в документации, плюс путь метода /me без лишних символов на конце

Метод запроса: GET, потому что этот вызов только читает данные и ничего не меняет

Заголовок: Authorization, в котором стоит токен целиком, без кавычек и пробелов

Ожидаемый ответ: код 200 и тело в формате JSON с именем и идентификатором бота

Способ передачи токена сверьте с актуальной версией документации, потому что в ранних примерах его передавали параметром в адресе. Если скопировать такой пример из старой статьи, токен может осесть в журналах прокси и сервера, а это уже повод его перевыпустить.

Такой запрос удобно сделать коротким скриптом на Python или TypeScript, и в обоих случаях я сразу печатаю код ответа и тело целиком, потому что в теле сервер обычно объясняет, что именно ему не понравилось, и эта строка экономит больше времени, чем любая догадка.

Когда сведения о боте пришли, следующий шаг: отправить одно сообщение самому себе через метод отправки, указав получателя параметром и текст в теле запроса. Именно здесь чаще всего путают идентификатор чата и идентификатор пользователя, и сервер честно отвечает ошибкой, которую легко принять за проблему с токеном.

Как бот получает сообщения: опрос или вебхук

Входящие события бот забирает одним из двух способов, и выбор определяет, где у вас потом будут ломаться вещи. При длинном опросе ваш скрипт сам регулярно спрашивает сервер о новых событиях, а при вебхуке сервер MAX присылает их на ваш адрес, как только они появились.

Длинный опрос удобен на старте, потому что ему не нужны публичный адрес, сертификат и открытый порт, а скрипт можно запустить на ноутбуке и увидеть первые события прямо в консоли. Слабое место в том, что после падения скрипта события нужно разобрать аккуратно, чтобы не ответить пользователю дважды.

Вебхук подходит рабочему боту, но добавляет свои точки отказа: адрес должен быть доступен снаружи по защищённому соединению, сертификат действителен, а ваш сервер обязан быстро отвечать успешным кодом. Самый коварный вебхук тот, что формально работает, но отвечает медленно, потому что внутри синхронно ждёт соседние системы.

Правило, которое спасает нервы: вебхук принимает событие, кладёт его в очередь и сразу отвечает, а обработка идёт отдельным процессом. Тогда медленная база или внешний сервис превращаются в задержку ответа пользователю, и сообщения при этом не теряются.

Как читать ответ сервера

Код ответа раскладывает все ошибки по трём корзинам, и от корзины зависит действие: чинить свой запрос, повторять его с паузой или искать ошибку в собственной логике. Путаница здесь стоит дорого: повтор с неверным токеном будет упираться в тот же отказ сколько угодно раз, и частый повтор при перегрузке только добавит сервису нагрузки.

Зелёная зона означает, что запрос выполнен, и если бот все равно молчит, ошибку ищите в своей логике обработки. В жёлтой зоне сервер просит подождать или временно не справляется, и такие запросы повторяют с растущей паузой, а в красной ошибка сидит в самом запросе, и повторять его бессмысленно, пока вы что-то не поменяли у себя.

Таблица ошибок API MAX: код, причина, что проверить

Эту таблицу я держу рядом с журналом ответов, и она закрывает большую часть вопросов в духе "почему бот молчит" ещё до того, как кто-то пойдёт писать в поддержку. Формат строки простой: код, что он значит и что проверить первым делом.

200, запрос выполнен: если результата нет, проверьте получателя, текст сообщения и свою логику обработки ответа.

400, сервер не понял запрос: проверьте, что тело корректно разбирается как JSON, обязательные поля на месте и идентификатор чата не перепутан с идентификатором пользователя.

401, токен не принят: проверьте заголовок Authorization, лишние пробелы и переносы строк при копировании, не перевыпущен ли токен и не остался ли старый в конфиге.

403, действие запрещено: проверьте, добавлен ли бот в чат, есть ли у него права администратора в канале и может ли он писать этому пользователю.

404, не найдено: проверьте путь метода, адрес сервера и существует ли чат или сообщение с тем идентификатором, который вы передаете.

405, не тот метод: проверьте по документации, что чтение идёт через GET, а отправка и изменения через POST или другой указанный метод.

429, слишком много запросов: сделайте паузу, повторяйте с растущим интервалом и пустите всю отправку через одну очередь с ограничением скорости.

500 и 503, сбой на стороне сервиса: повторите позже, запишите время и тело ответа, а токен и настройки в этот момент не трогайте.

Ответа нет совсем, сработал таймаут: проверьте сеть, прокси и правила межсетевого экрана для исходящих соединений с вашего сервера.

Вебхук молчит: проверьте, доступен ли адрес снаружи, действителен ли сертификат, зарегистрирована ли подписка и насколько быстро ваш сервер отвечает.

Точные тексты ошибок и дополнительные коды смотрите в документации, а таблицу дополняйте своими строками по мере того, как находите новые причины: каждая такая строка экономит следующему разработчику целый вечер.

Если бот нужен в работе быстро, а разбираться с очередями, вебхуками и журналами некому, эту часть мы в PROMAREN берём на себя и собираем ботов для MAX на Python и TypeScript, с очередью и журналом ответов с первого дня. Когда задача решается одним скриптом по этой статье, я так и скажу, потому что брать лишнюю работу невыгодно обеим сторонам.

Частые вопросы про API MAX

Где взять токен для бота в MAX?

Токен выдаётся при создании бота на платформе MAX для партнёров, и порядок вместе с требованиями к владельцу описан в официальной документации для разработчиков. Храните его в переменной окружения или в хранилище секретов, чтобы он не попал в репозиторий и чужие журналы.

Почему API MAX возвращает ошибку 401?

Код 401 означает, что сервер не принял токен, он может быть передан не тем способом, скопирован с лишним пробелом или переносом строки. Ещё одна причина в том, что токен перевыпустили, а старый остался в конфиге тестового сервера или в забытом скрипте.

Что выбрать для бота MAX: длинный опрос или вебхук?

Для старта удобнее длинный опрос, потому что ему не нужны публичный адрес и сертификат, и скрипт можно запустить прямо на ноутбуке. Для рабочего бота подходит вебхук, который принимает событие, кладёт его в очередь и сразу отвечает успешным кодом.

Нужно ли повторять запрос при ошибке API MAX?

Повторять имеет смысл только при перегрузке и сбоях на стороне сервиса, и делать это стоит с растущей паузой между попытками. При ошибках в самом запросе повтор бесполезен, пока вы не исправили токен, адрес, права или тело запроса у себя.

Что проверить у себя сегодня

Если бот у вас уже работает, пройдите по этим пунктам за один присест, в любом порядке, потому что они не зависят друг от друга и каждый отвечает за свой класс поломок:

Отдельно откройте журнал за последние дни и посмотрите, сколько там ответов из жёлтой и красной зоны, потому что красные коды в рабочем боте почти всегда означают ошибку, которая повторяется на каждом запросе и которую никто пока не заметил.

Какой код ответа стоил вам больше всего нервов, когда вы подключали своего бота?

Новые разборы выходят в моём канале: t.me/promaren.