LINE X-Line-Retry-Key: повтор отправки после тайм-аута без дублей
Для поддерживаемых методов отправки LINE Messaging API добавляйте X-Line-Retry-Key уже в первый запрос. После тайм-аута или допускающей повтор серверной ошибки используйте тот же ключ, получателя и содержимое. Для каждого нового логического запроса создавайте UUID в шестнадцатеричной записи. Если 409 означает, что ключ уже принят, остановитесь, а не создавайте новый ключ. Это предотвращает повторное принятие в пределах установленного срока, но не гарантирует доставку пользователю.
Главное
- Ключ поддерживают push, multicast, narrowcast и broadcast, а не все API LINE.
- Сохраняйте ключ и исходный запрос до отправки, а не после ошибки.
- По документации LINE ключ действует 24 часа с первого запроса.
- Принятие запроса, доставка получателю и подтверждение входящего webhook — разные результаты.
От каких дублей защищает X-Line-Retry-Key
Тайм-аут означает, что приложение не получило ответ. LINE при этом могла уже принять отправку. Новый UUID на каждой попытке превращает неопределённый результат в ещё один независимый запрос.
В руководстве LINE по повторам описан другой механизм: после принятия запроса с ключом последующие попытки с тем же ключом отклоняются как дубли. Ключ нужен с первой попытки. Если исходный запрос ушёл без ключа, добавление ключа после тайм-аута не защитит его задним числом.
| Метод отправки | Поддержка ключа по документации LINE |
|---|---|
| Push | Да |
| Multicast | Да |
| Narrowcast | Да |
| Broadcast | Да |
| Другие API, включая reply messages | Не входят в этот список; не добавляйте заголовок ко всем вызовам |
LINE указывает, что использование заголовка с неподдерживаемым API приводит к 400. Этот механизм также не относится к notification token в LINE MINI App. Для такой интеграции используйте разбор ошибок Service Message API, а не правила из этой статьи.
Сначала сохраните запись отправки
Далее приведены рекомендации по архитектуре приложения, а не дополнительные поля LINE API.
Создайте устойчивую запись исходящей операции: идентификатор бизнес-действия, канал, метод отправки, полное тело запроса, UUID повтора, время первой попытки, крайний срок повторов и состояние обработки. Защищайте данные получателя и текст согласно своей политике хранения. Токены доступа загружайте из защищённой конфигурации, не помещайте их в запись задания или обычные журналы.
Отправляйте только после сохранения записи. При повторе загружайте сохранённые ключ и запрос, а не собирайте сообщение заново из изменяемых данных заказа или клиента. LINE прямо запрещает менять получателя и содержимое при повторе с тем же ключом.
Задайте уникальный идентификатор бизнес-операции и механизм захвата задания или блокировки для воркера. Иначе два воркера могут создать разные UUID для одного действия, и оба запроса будут приняты. Ключ устраняет дубли конкретного запроса, но не определяет, что два независимо созданных задания имеют одинаковый смысл.
Если один Official Account используют несколько инструментов, назначьте владельца каждого типа отправок. Чек-лист подключения нескольких инструментов описывает общий канал, а локальный outbox определяет владельца отдельной исходящей операции.
Выбирайте действие по фактическому результату
Следуйте правилам LINE для HTTP-статусов. Не считайте любой неуспешный ответ разрешением отправить ещё раз.
| Результат | Рекомендуемое действие воркера |
|---|---|
2xx | Сохранить факт принятия и завершить повторы |
| Тайм-аут или серверная ошибка, допускающая повтор | Запланировать ограниченный повтор с исходным ключом и неизменным запросом |
409, означающий, что ключ уже принят | Сохранить x-line-accepted-request-id, зафиксировать прежнее принятие и остановиться |
Другой 4xx | Остановить неизменные повторы, проверить запрос или ограничение |
| Срок истёк, принятие не подтверждено | Передать на сверку или оператору, не менять ключ автоматически |
При ответе о ранее принятом запросе LINE возвращает x-line-accepted-request-id — идентификатор успешного запроса. Не путайте его с x-line-request-id, относящимся к отдельной попытке. Сохраняйте статусы, время и диагностические данные без секретов; не стройте обработку только на тексте ошибки.
LINE рекомендует экспоненциальную задержку и предупреждает, что повторы учитываются в ограничении частоты запросов. Планировщик должен иметь собственный лимит попыток и не назначать их за пределами 24 часов действия ключа. Срок начинается с первого запроса, а не заново после каждой попытки. Приложение может установить более раннюю границу.
По истечении срока неизвестный результат остаётся неизвестным. Новый ключ означает новое решение об отправке и может продублировать уже принятое сообщение. Требуйте сверку или явное одобрение, а не используйте замену ключа как обычный способ восстановления.
Принятие не равно доставке
LINE прямо указывает: ключ повтора не гарантирует доставку получателю. Например, пользователь мог заблокировать Official Account, поэтому принятие запроса не доказывает получение сообщения. После принятия повторение того же ключа не служит способом исправить доставку.
В приложении различайте «LINE приняла запрос» и «клиент прочитал сообщение». Аналогично успешный ответ вашего webhook-приёмника подтверждает входящую доставку, но не отправку исходящего ответа.
Контракт UnifyPort нужно рассматривать отдельно
Неофициальный интерфейс UnifyPort подключает аккаунты обмена сообщениями и передаёт нормализованные события, например message.received. Это не дополнительный отправитель внутри того же канала LINE Official Account Messaging API. Публичная документация отправки UnifyPort не заявляет поддержку X-Line-Retry-Key.
Перед реализацией повторов изучите контракт отправки текста. Не переносите в него срок 24 часа или ответы о повторном принятии из LINE. Идентификатор трассировки сам по себе также не гарантирует идемпотентность.
Для входящих событий настройте signing_secret и проверяйте X-Device-Signature: HMAC-SHA256 от X-Device-Timestamp, точки и исходного тела запроса. Правила подтверждения и повторов описаны в документации доставки webhook. Дедупликация входящих событий и исходящих отправок решает разные задачи: одна не заменяет другую.
Если нужны функции отправки Official Account, используйте официальный Messaging API. Переход на интерфейс обычного аккаунта не устраняет неопределённость запроса, уже отправленного через официальный API.
Вопросы и ответы
Можно создать ключ после первого тайм-аута?
Не для защиты исходного запроса. На поддерживаемом API ключ должен присутствовать с первой попытки.
После 409 нужно отправить с новым UUID?
Нет, если ответ означает, что тот же ключ уже принят. Сохраните идентификатор принятого запроса и завершите повторы операции.
Можно оставить ключ, но поменять получателя?
Нет. По требованиям LINE содержимое и получатель должны совпадать с исходным запросом. Изменение бизнес-действия требует отдельного решения, а не изменения повтора.
Это работает для всех API сообщений LINE?
Нет. Только для перечисленных поддерживаемых методов. Не применяйте этот контракт к MINI App service messages или отправкам UnifyPort.
Следующий шаг и источники
Проверьте исходящий воркер: сможет ли он после сбоя восстановить тот же ключ и тот же запрос? Сначала протестируйте эту границу на локальной имитации сервиса, затем выполните контролируемую отправку. Для интеграции подключённого аккаунта изучите справочник отправки UnifyPort.
Официальные источники проверены 2026-09-28:
Превратите интеграцию сообщений в стабильный продуктовый pipeline.
Начните с отправки через единый API, затем возвращайте входящие сообщения в бизнес-систему стандартными событиями.