LINE MINI App Service Message API 错误排查：400、401、403、429 与 500
排查 LINE MINI App Service Message API 错误时，先确认失败发生在 token 签发还是消息发送。400、401、403 通常表示请求、凭据或权限状态不匹配；429 需要降速；500 应先保留证据再谨慎重试。每次发送成功后，必须先原子保存返回的新 notification token，才能让下一个任务继续发送。
核心结论
POST /message/v3/notifier/token与POST /message/v3/notifier/send?target=service可能返回相同状态码，但原因不同，因此日志必须同时记录操作阶段。- 用户关闭 LIFF app 后，LIFF access token 即使尚未到期也可能被撤销。
- 成功发送通常会更新 service notification token；应把新 token、
remainingCount、expiresIn原子保存。 429代表需要降低流量，而不是缩短重试间隔；LINE 明确要求不要对生产平台做大量请求测试。- 不要盲目重放结果不确定的发送。官方参考文件没有为该 endpoint 说明 idempotency key。
LINE MINI App Service Message API 状态码表
LINE 官方 API Reference包含两个服务端调用：token endpoint 用一个 LIFF access token 换取与单个用户绑定的 service notification token；send endpoint 用该 token 和已批准模板发送消息。
| 状态 | token 签发 | 消息发送 | 首要检查 |
|---|---|---|---|
400 Bad Request | body 无效，或短时间内重复使用同一个 LIFF access token 签发 token | body、模板参数无效，或目标用户不存在 | 按失败 endpoint 校验实际请求 |
401 Unauthorized | channel access token 或 LIFF access token 无效 | channel access token 或 service notification token 无效 | 确认本操作需要哪一种 token，不能混用 |
403 Forbidden | channel 无权签发 service message | channel 无权发送，或找不到 templateName | 检查 channel 环境、认证状态和模板部署 |
429 Too Many Requests | 请求速率超限 | 请求速率超限 | 停止合成流量，退避并降低并发 |
500 Internal Server Error | 官方签发表将其列为 server error | 如果 send 返回 5xx，按运行事故处理；send 专用表没有列出 500 | 保存证据、查看官方通知，再谨慎重试 |
这个表只负责分流，不能替代 response body。日志应记录状态码、endpoint、请求时间、脱敏后的响应、channel/环境标识、模板名和内部 job ID。access token 与 notification token 应放在凭据存储中；业务日志只记录单向指纹，既能关联问题，又不暴露凭据。
排查步骤：先确认失败状态，再决定是否重试
1. 分开处理 token 签发与消息发送
签发阶段要确认浏览器从当前 LIFF session 获取 token，并且只把它提交一次给后端。Service Message API 还需要 channel access token，因此不要从浏览器直接调用。LINE 只允许一个 LIFF access token 签发一个 service notification token。
发送阶段要分别校验 channel access token、最新的 service notification token，以及带受支持 BCP 47 后缀的 templateName，例如 _ja、_en、_zh-TW、_th。token 正确不能弥补 channel 中缺失的模板。
notification token 教程说明正常的两次调用流程；只有在能明确指出哪一次调用失败后，再使用本文的故障流程。
2. 把 400 当作 endpoint 特定的校验错误
签发 token 时，检查按钮是否触发两次，或前端重试是否重复提交了已使用的 LIFF access token。发送消息时，把 params 与批准模板逐项对齐，并在派发前校验字符限制。LINE 说明，变量值超过模板 hard limit 时无法发送。
不要通过轮换全部凭据来处理 400。修正请求或用户状态，再以新的 job ID 创建业务操作。上线前可用模板送审清单核对变量和链接。
3. 按 token 的归属和生命周期处理 401
日志只记录失败的 token 类型，不记录 token 值：
- Channel access token：授权 MINI App channel；LINE 建议 MINI App channel 使用 stateless 或短期 channel access token。
- LIFF access token：证明当前用户 session，用于签发；关闭 LIFF app 时可能被撤销。
- Service notification token：只属于一个用户，不能转给另一个用户。
如果用户在后端交换 token 前关闭了 app，应重新打开流程并取得新 LIFF token。如果发送失败，确认 worker 读取的是最近一次成功发送后更新的 notification token，而不是队列快照中的旧值。
4. 把 403 当作权限或部署环境不匹配
签发时出现 403，表示 channel 无权签发 service message；发送时出现 403，还可能表示模板不存在。确认调用使用预期的 Developing 或 Published channel、本番资格已满足，并且对应 locale 的模板已反映到该 channel。
把 MINI App 从未认证改为已认证，不能修复错误的模板名；模板名正确，也不会自动让未认证 Published channel 获得生产权限。认证与未认证限制指南把这两个判断拆开说明。
5. 串行保存更新后的 notification token
成功发送后，只要 token 仍有效且有剩余次数，LINE 会更新 service notification token。应把响应视为状态迁移：
读取当前 token -> 发送一次 -> 保存返回 token 和计数 -> 释放下一个任务使用数据库事务、compare-and-set 版本或单用户队列，避免两个 worker 同时使用旧 token。如果 expiresIn 与 remainingCount 都是 0，LINE 表示消息已经发出，但 token 无法续期。此时发送应记为成功，同时停止安排下一条 service message。
6. 只在结果可以安全重复时重试
在请求、凭据或权限状态改变前，不要重试 400、401、403。遇到 429 时使用带 jitter 的退避并降低并发，不要用生产 API 做负载测试。遇到明确的 500，先保存请求记录并查看 LINE status/news，再由受控 job 谨慎重试。
最危险的是请求发出后超时：客户端无法知道 LINE 是否已经接受消息并更新 token。由于官方参考文件没有说明 idempotency key，盲目重试可能让用户收到重复通知。应把结果不确定的任务送入对账或人工复核，而不是当成普通瞬时失败。
UnifyPort 适合承接哪一部分
UnifyPort 不签发 LINE service notification token，不审批 MINI App 模板，不改变认证状态，也不替代官方 Service Message API 的故障排查。与 MINI App 操作绑定的事务通知，应使用 LINE 官方路径。
UnifyPort 适合承接另一项独立需求：接收已连接 LINE 账号的普通客户消息。受支持的入站消息会以标准化的 message.received 事件送达。如果 webhook endpoint 配置了 signing_secret，投递会携带 X-Device-Timestamp 与 X-Device-Signature；路由会话前，应使用 raw body 验证 HMAC-SHA256 签名。
两套状态机要保持分离。service notification token 属于 LINE MINI App 事务流程；客户回复属于客服消息流程。可在自己的系统中通过订单或预约 ID 关联它们，不要复用平台 token。
限制与权衡
如果已认证 MINI App 需要发送批准的确认、结果或提醒，官方 Service Message API 是正确选择。它提供平台原生模板、身份和政策控制，这是非官方接口无法提供的。
非官方接口不能取消 LINE 资格规则、恢复过期 notification token、增加五条消息上限，也不能把客服回复变成 service message。它的职责更窄：通过统一入站 API 交付受支持的普通会话。
FAQ
为什么未到期的 LIFF access token 会返回 401？
LINE 说明，用户关闭 LIFF app 后，token 即使尚未到期也可能被撤销。应从新的 LIFF session 获取 token，并且只交换一次。
为什么 token 签发成功，发送却返回 403？
签发和发送的检查不同。发送可能因为 channel 没有对应环境权限，或 templateName 在该 channel 中不存在而失败。
LINE service message 超时后可以重试吗？
不能盲目重试。响应丢失时，消息可能已经发送，notification token 也可能已经变化。由于 endpoint 没有公开的 idempotency key，应先对账再决定是否重发。
Service Message API 事故应记录哪些日志？
记录请求时间、method、endpoint、status、脱敏响应、channel/环境、模板名、job ID 和安全 token 指纹。真实 token 只放在受保护的凭据存储中。
200 响应中 remainingCount: 0、expiresIn: 0 表示什么？
消息已经发出，但 LINE 无法更新 service notification token。应把本次投递记为成功，且不要再用该 token 安排发送。
下一步
先根据官方 LINE MINI App API Reference实现状态分流，并在发布前为两个 endpoint 各测试一次受控失败。如果另一项需求是接收普通 LINE 客服消息，请在官方通知流程稳定后阅读 UnifyPort LINE 授权指南。
来源
以下 LINE 官方来源核验于 2026-08-06：