Ошибки LINE MINI App Service Message API: разбор 400, 401, 403, 429 и 500
Ошибку LINE MINI App Service Message API проще диагностировать после разделения двух операций: выдачи service notification token и отправки сообщения. 400, 401 и 403 обычно требуют исправить request, credential или permission; после 429 нужно снизить нагрузку; при 500 сначала сохраните доказательства. После успешной отправки атомарно сохраните новый notification token до запуска следующего worker.
Главное
POST /message/v3/notifier/tokenиPOST /message/v3/notifier/send?target=serviceмогут вернуть одинаковый status по разным причинам, поэтому логируйте endpoint и этап.- LIFF access token может быть отозван, когда пользователь закрывает LIFF app, даже до истечения срока.
- Успешная отправка обычно обновляет service notification token; сохраняйте новый token вместе с
remainingCountиexpiresIn. 429требует снизить частоту, а не ускорять retry. LINE запрещает создавать большую тестовую нагрузку на platform API.- Не повторяйте отправку с неизвестным результатом вслепую: для этого endpoint официальный reference не описывает idempotency key.
Таблица ошибок LINE MINI App Service Message API
Официальный LINE MINI App API reference описывает два server-side вызова. Token endpoint обменивает LIFF access token на service notification token, связанный с одним пользователем. Send endpoint использует этот token и одобренный template.
| Status | Выдача token | Отправка | Первая проверка |
|---|---|---|---|
400 Bad Request | Некорректный body или повторное использование одного LIFF access token за короткое время | Некорректный body/params или получатель не существует | Проверьте request конкретного endpoint |
401 Unauthorized | Неверный channel access token или LIFF access token | Неверный channel access token или service notification token | Определите тип token для операции |
403 Forbidden | Channel не имеет права выдавать token | Channel не авторизован или templateName не найден | Проверьте environment, verification и deployment template |
429 Too Many Requests | Превышен rate | Превышен rate | Остановите тестовый traffic, включите backoff и снизьте concurrency |
500 Internal Server Error | Указан в официальной таблице выдачи как server error | Если send вернул 5xx, считайте это incident; в таблице send-specific 500 не указан | Сохраните evidence и проверьте официальные notices |
Таблица служит маршрутизатором, а не заменой response body. Сохраняйте status, endpoint, время, redacted response, channel/environment, template name и собственный job ID. Настоящие access token и notification token храните только в secret store, а в application logs используйте односторонний fingerprint.
Runbook: определите состояние до retry
1. Разделите выдачу token и отправку
При выдаче проверьте, что browser получил token из текущей LIFF session и отправил его backend только один раз. Не вызывайте Service Message API из browser: для него также нужен channel access token. Один LIFF access token разрешено обменять только на один service notification token.
При отправке отдельно проверьте channel access token, актуальный service notification token и templateName с поддерживаемым BCP 47 suffix, например _ja, _en, _zh-TW или _th. Корректный token не исправит отсутствие template в channel.
Нормальный flow из двух вызовов описан в руководстве по notification token. Используйте этот runbook, когда точно знаете, какой вызов завершился ошибкой.
2. Обрабатывайте 400 в контексте endpoint
При выдаче найдите двойной click или frontend retry, который повторно отправил использованный LIFF access token. При отправке сравните params с одобренным template и проверьте ограничения длины до dispatch. LINE сообщает, что значение длиннее hard limit отправить нельзя.
Не меняйте все credentials из-за 400. Исправьте request или user state и создайте новую business operation с новым job ID. Переменные и ссылки можно проверить по чек-листу review template.
3. Для 401 проследите владельца и lifetime token
- Channel access token авторизует MINI App channel; LINE рекомендует stateless или short-lived token.
- LIFF access token подтверждает текущую user session и может быть отозван при закрытии LIFF app.
- Service notification token принадлежит одному пользователю и не переносится другому.
Если пользователь закрыл app до обмена на backend, начните LIFF flow заново. Если ошибка возникла при send, убедитесь, что worker загрузил token из последнего успешного response, а не старое значение из queue snapshot.
4. Считайте 403 несовпадением permission или deployment
403 при выдаче означает, что channel не может выдавать service message token. При отправке он также может означать отсутствие template. Проверьте Developing/Published channel, production eligibility и отражение template нужной locale.
Verification MINI App не исправляет неправильное имя template. И наоборот, корректный template не даёт production permission непроверенному Published channel. Эти условия разделены в руководстве verified vs unverified.
5. Сериализуйте запись обновлённого notification token
После успешной отправки LINE обновляет token, пока остаются lifetime и message count. Рассматривайте response как state transition:
загрузить token -> отправить один раз -> сохранить новый token и counters -> запустить следующий jobИспользуйте database transaction, compare-and-set version или per-user queue, чтобы два worker не взяли один старый token. Если expiresIn и remainingCount равны 0, сообщение отправлено, но token не обновлён. Зафиксируйте успех и не планируйте следующую service message с этим token.
6. Повторяйте только безопасный outcome
Не retry 400, 401 и 403, пока не изменился request, credential или authorization state. Для 429 используйте backoff с jitter и уменьшите concurrency; не выполняйте load test production API. При явном 500 сохраните request record, проверьте LINE status/news и запускайте контролируемый retry.
Timeout после dispatch опаснее: client может не знать, принял ли LINE message и обновил ли token. Без документированного idempotency key blind retry может создать дубликат уведомления. Направляйте неопределённый outcome на reconciliation или operator review.
Где подходит UnifyPort
UnifyPort не выдаёт LINE service notification token, не утверждает MINI App template, не меняет verification status и не устраняет ошибки официального Service Message API. Для transactional notification после действия в MINI App используйте официальный путь LINE.
UnifyPort решает отдельную задачу: получает обычные сообщения клиентов из подключённого LINE account. Поддерживаемые входящие сообщения приходят как нормализованные события message.received. Если endpoint имеет signing_secret, delivery содержит X-Device-Timestamp и X-Device-Signature; перед routing проверьте HMAC-SHA256 по raw body.
Не объединяйте две state machine. Service notification token относится к MINI App transaction flow, а reply клиента — к support flow. Связывайте их собственным order или reservation ID, а не общим platform token.
Ограничения и компромиссы
Официальный Service Message API нужен, когда verified MINI App отправляет одобренные confirmations, results или reminders. Он предоставляет platform-native template, identity и policy controls, которых нет у unofficial interface.
Unofficial interface не отменяет eligibility LINE, не восстанавливает истёкший token, не увеличивает лимит в пять сообщений и не превращает support reply в service message. Его роль — доставка поддерживаемых обычных conversations через единый inbound API.
FAQ
Почему LIFF access token до истечения срока возвращает 401?
LINE может отозвать его после закрытия LIFF app. Получите новый token из новой LIFF session и обменяйте его один раз.
Почему после успешной выдачи token отправка возвращает 403?
Endpoint проверяют разное. Send может не иметь permission в данном environment или не найти templateName в channel.
Можно ли retry service message после timeout?
Не вслепую. Message и token могли уже изменить состояние. Сначала выполните reconciliation.
Что записывать в incident log?
Время, method, endpoint, status, redacted response, channel/environment, template, job ID и безопасный token fingerprint. Сами token храните в защищённом store.
Что означает remainingCount: 0 и expiresIn: 0 после 200?
Message отправлен, но LINE не смог обновить notification token. Зафиксируйте успех и не используйте этот token снова.
Следующий шаг
Постройте status dispatcher по официальному LINE MINI App API reference и до release проверьте по одному контролируемому failure на каждом endpoint. Для отдельной задачи приёма обычных LINE сообщений после стабилизации уведомлений изучите руководство авторизации LINE в UnifyPort.
Источники
Официальные источники LINE проверены 6 августа 2026 года: