Ошибка API в Telegram Mini App не должна превращаться в потерю формы или бесконечную загрузку. Человек мог уже выбрать услугу, приложить файл и написать подробности. Если приложение на любой отказ очищает экран, техническая проблема становится дополнительной работой пользователя.
Правильная обработка начинается с различения чтения, сохранения черновика и окончательной операции. Их повтор имеет разные последствия. Ниже разобран процесс восстановления интерфейса при сбое сети и сервера. Речь об API вашего приложения и внешних сервисов, а не об обещании одинаковых кодов ошибок для всех компонентов Telegram.
Классификация по действию пользователя
Ошибка загрузки каталога отличается от неизвестного результата создания заявки. В первом случае повтор чтения обычно не создаёт новый объект. Во втором операция могла выполниться, а ответ потеряться. Если оба случая показывают одну кнопку «повторить» с одинаковой логикой, возможны дубликаты.
Отдельно выделите ошибку проверки данных, отсутствие доступа и временную недоступность. Неправильное поле исправляет пользователь; изменившуюся сессию обрабатывает вход; временный отказ может требовать ожидания. Не заставляйте человека многократно повторять один запрос, если его параметры заведомо не подходят.
Сообщение должно описывать доступный следующий шаг. Технический код полезен поддержке, но не заменяет человеческое объяснение. При этом не утверждайте, что данные не сохранены, если серверный результат неизвестен. Честное состояние проверки лучше уверенного неверного ответа.
Сохраните пользовательский ввод
Не очищайте поля из-за сетевого отказа. Состояние формы отделяют от состояния запроса. Если пользователь может редактировать текст после ошибки, приложение должно понимать, что следующая отправка относится к новой версии данных, а не незаметно повторяет старую.
Для важных черновиков предусмотрите поддерживаемый механизм хранения и понятный индикатор результата. Но локальная копия не заменяет подтверждённое серверное сохранение. Показывайте соответствующий смысл, особенно если человек собирается закрыть приложение и продолжить на другом устройстве.
Вложения также требуют учёта. Файл мог загрузиться до отказа финальной операции. Повтор не должен отправлять его бесконечно или терять связь с анкетой. Используйте идентификаторы уже принятых материалов и проверяйте их пригодность в текущем экземпляре формы.
Условный пример: ответ о заявке потерялся
Предположим, пользователь нажал отправку. Сервер создал заявку, но соединение оборвалось до получения номера. Приложение не знает результата и показывает состояние проверки. По сохранённому идентификатору операции оно запрашивает существующий результат, а не сразу создаёт вторую заявку.
Если результат подтверждён, клиент получает номер и дальнейший путь. Если операция действительно не началась, разрешается повтор по согласованному контракту. Если выяснить состояние автоматически нельзя, вопрос передаётся в предусмотренный разбор с сохранёнными данными, без требования заполнить всё заново.
Пример условный. Telegram не обеспечивает идемпотентность вашего серверного метода автоматически. Для такой схемы нужны поддерживаемые идентификаторы, проверка состояния и хранение результатов в приложении. Один красивый экран повторной попытки не даёт этих свойств сам по себе.
Загрузка и доступность кнопок
Показывайте ожидание для текущего действия и не блокируйте без причины весь интерфейс. Пользователь может читать введённые данные или вернуться к безопасному шагу. Но изменение параметров во время окончательной операции должно иметь определённое поведение, иначе сервер получит один вариант, а экран покажет другой.
Блокировка кнопки помогает избежать случайного повтора, но не заменяет серверную проверку. Другой клиент, перезагрузка или задержанный запрос всё равно могут привести к повтору. У бизнес-операции должен быть собственный ключ и понятный результат независимо от состояния одного элемента интерфейса.
Если запрос завершился ошибкой, уберите индикатор ожидания и предложите допустимое продолжение. Вечная анимация хуже ясного отказа: человек не знает, можно ли закрывать форму. Ограничение времени ожидания выбирают по задаче и проверяют вместе с фактической обработкой на сервере.
Сессия и права
Если доступ истёк, приложение должно безопасно восстановить вход либо объяснить необходимость нового запуска поддерживаемым способом. Не превращайте ошибку авторизации в бесконечный повтор того же запроса. Новая сессия не должна выдавать доступ к чужим данным по старому идентификатору из локального состояния.
При изменении роли сервер может запретить операцию, которая ещё отображается на старом экране. Интерфейс должен обработать это как ожидаемое изменение доступа, сохранив допустимые данные и понятный путь. Скрытие кнопки после обновления удобно, но окончательная защита находится на сервере.
Не показывайте клиенту подробные внутренние сообщения об ошибках с секретами, трассировками и чужими идентификаторами. Используйте короткий диагностический номер и разрешённый путь поддержки. В журнале сохраняйте необходимую техническую причину с контролем состава данных.
Возврат в приложение
Пользователь может свернуть Mini App во время запроса и вернуться после завершения. Экран должен сверить состояние, а не повторно выполнить действие только потому, что компонент появился снова. Побочный эффект нельзя привязывать к любому повторному отображению страницы без контроля операции.
После перезагрузки проверьте сохранённый идентификатор заявки и актуальную сессию. Если операция завершена, покажите результат. Если черновик остался незавершённым, предложите продолжение по правилам формы. Не смешивайте эти состояния в один универсальный стартовый экран.
Отдельно испытайте возврат из нативного окна разрешения и выбора файла. События интерфейса могут завершаться в разном порядке. Приложению нужен один понятный источник состояния, чтобы старый callback не очистил уже исправленный ответ и не переключил экран после нового действия человека.
Проверочный набор отказов
Смоделируйте отсутствие сети до запроса, разрыв после отправки, медленный ответ и серверную ошибку. Затем добавьте неверное поле, отсутствие прав и конфликт версии объекта. Для каждого случая заранее определите, что сохраняется и какое действие доступно пользователю.
Проверьте два нажатия, перезагрузку и возвращение с другого устройства. Сравните количество реальных записей в серверной системе. Если интерфейс показывает один успех, а база содержит два объекта, проверка не пройдена. Конечный результат важнее внешней гладкости сценария.
Приёмка готова, когда приложение объясняет отказ, сохраняет нужные сведения и умеет определить результат операции. Ошибки будут возникать и после запуска. Ценность интерфейса в том, что человек может продолжить работу без догадок, повторного ввода и случайных дополнительных последствий.
Запрос завершён, но экран уже изменился
Человек может уйти на другой маршрут, пока запрос выполняется. Поздний ответ не должен внезапно вернуть его на старую форму или очистить новое описание. Обработчик связывает результат с конкретной операцией и актуальной версией интерфейса, а не просто применяет любые пришедшие данные к текущему экрану.
Это особенно важно при поиске, загрузке справочника и сохранении черновика. Старый ответ может прийти после нового. Если он перезапишет актуальное состояние, пользователь увидит неправильные варианты и решит, что приложение игнорирует выбор. Нужен согласованный механизм отмены либо проверки актуальности результата.
Для окончательной бизнес-операции уход с экрана не обязательно отменяет исполнение. Поэтому различайте прекращение ожидания в интерфейсе и реальную отмену на сервере. После возвращения приложение выясняет состояние, а не делает вывод по тому, какой компонент был закрыт.
На испытании замедлите тестовый ответ, перейдите на другой шаг и выполните новое действие. Проверьте порядок прихода результатов. Приложение должно сохранить текущую задачу, показать завершённую операцию в подходящем месте и не запустить повтор из-за одного изменения маршрута.
Источники
Жизненный цикл и события оболочки описаны в Telegram Mini Apps. Принципы ограниченных повторов обсуждаются в AWS Builders’ Library. Контракт ошибок и идемпотентность вашего API определяются отдельно.