← 所有文章
教學

LINE MINI App Service Message API 錯誤排查：400、401、403、429 同 500

排查 LINE MINI App Service Message API 錯誤，第一步係確認失敗發生喺 token 簽發定訊息傳送。400、401、403 通常係 request、credential 或權限狀態唔一致；429 要降速；500 應先保存證據再審慎 retry。每次傳送成功後，要先原子保存 response 入面嘅新 notification token，先可以畀下一個工作繼續。

重點摘要

  • POST /message/v3/notifier/token 同 POST /message/v3/notifier/send?target=service 可以回傳同一 status，但原因唔同，所以 log 一定要記錄操作階段。
  • 用戶關閉 LIFF app 後，LIFF access token 就算未到期都可能被撤銷。
  • 成功傳送通常會更新 service notification token；要一齊保存新 token、remainingCount 同 expiresIn。
  • 429 代表要減少流量，唔係縮短 retry 間隔；LINE 明確要求唔好對平台發大量測試 request。
  • 唔好盲目重送結果未明嘅 send。官方 API reference 冇為呢個 endpoint 說明 idempotency key。

LINE MINI App Service Message API 錯誤表

LINE 官方 API reference有兩個 server-side call：token endpoint 用 LIFF access token 換取綁定單一用戶嘅 service notification token；send endpoint 用呢個 token 同已批准 template 傳送訊息。

Statustoken 簽發訊息傳送第一個檢查
400 Bad Requestbody 無效，或者短時間內重用同一 LIFF access tokenbody、template params 無效，或者目標用戶不存在按失敗 endpoint 驗證 request
401 Unauthorizedchannel access token 或 LIFF access token 無效channel access token 或 service notification token 無效確認操作需要邊一種 token
403 Forbiddenchannel 冇權簽發channel 冇權傳送，或者搵唔到 templateName檢查環境、認證狀態同 template 部署
429 Too Many Requestsrate 超限rate 超限停止合成流量、退避同降低並發
500 Internal Server Error官方簽發表列為 server error如果 send 回傳 5xx，按營運事故處理；send 專用表冇列出 500保存證據並查看官方通知

呢張表只用嚟分流，唔可以取代 response body。請記錄 status、endpoint、request time、已脫敏 response、channel/環境、template 名同內部 job ID。真正 access token 同 notification token 要放入安全 credential store；應用 log 只保存單向 fingerprint。

排查流程：先確認狀態，再決定 retry

1. 分開 token 簽發同訊息傳送

簽發時，確認 browser 由目前 LIFF session 取得 token，而且只交畀 backend 一次。Service Message API 亦需要 channel access token，所以唔好喺 browser 直接 call。LINE 只容許一個 LIFF access token 簽發一個 service notification token。

傳送時，分別驗證 channel access token、最新 service notification token，同帶受支援 BCP 47 suffix 嘅 templateName，例如 _ja、_en、_zh-TW、_th。有效 token 唔可以補救 channel 入面不存在嘅 template。

notification token 教學講正常兩次 call；先指出邊個 call 失敗，再套用本文 runbook。

2. 按 endpoint 修正 400

簽發階段要檢查 button 有冇觸發兩次，或者 frontend retry 有冇重複提交已使用嘅 LIFF access token。傳送階段要將 params 同已批准 template 逐項比對，dispatch 前驗證字數限制；超過 hard limit 就唔可以傳送。

唔好靠輪換所有 credential 處理 400。修正 request 或用戶狀態，再以新 job ID 建立工作。可用template 送審清單預先驗證變數同 link。

3. 按 token 歸屬同生命週期處理 401

  • Channel access token 授權 MINI App channel；LINE 建議用 stateless 或短期 token。
  • LIFF access token 證明目前用戶 session，關閉 LIFF app 時可能被撤銷。
  • Service notification token 只屬於一位用戶，唔可以轉移。

如果用戶喺 backend exchange 前關閉 app，請重新開啟流程取得新 LIFF token。send 失敗時，確認 worker 載入最近成功 send 後更新嘅 notification token，唔係 queue snapshot 入面嘅舊值。

4. 將 403 視為權限或部署唔一致

簽發時嘅 403 代表 channel 冇權簽發；傳送時仲可能代表 template 不存在。確認 call 用正確 Developing 或 Published channel、production 資格已滿足，而且目標 locale template 已套用。

認證 MINI App 唔會修正錯誤 template 名；正確 template 亦唔會令未認證 Published channel 自動有 production 權限。認證與未認證限制指南分開講清楚兩項判斷。

5. 串行保存更新後嘅 notification token

成功 send 後，只要 token 仲有效同有剩餘次數，LINE 就會更新 token。將 response 當成 state transition：

讀取目前 token -> 傳送一次 -> 保存回傳 token 同計數 -> 釋放下一個工作

用 database transaction、compare-and-set version 或 per-user queue，避免兩個 worker 同時用舊 token。如果 expiresIn 同 remainingCount 都係 0，代表訊息已傳送，但 token 無法更新；應標記成功並停止後續 service message。

6. 只喺可以安全重複時 retry

喺 request、credential 或 authorization 狀態改變前，唔好 retry 400、401、403。遇到 429 就用 jitter 退避同降低並發；唔好用 production API 做 load test。遇到明確 500，先保留 request record、睇 LINE status/news，再由受控 job 審慎 retry。

如果 dispatch 後 timeout，client 可能唔知 LINE 有冇接受訊息同更新 token。因為冇公開 idempotency key，盲目 retry 可能產生重複通知。將不確定結果送去 reconciliation 或人工複核。

UnifyPort 適合嘅範圍

UnifyPort 唔簽發 LINE service notification token、唔批准 MINI App template、唔改變認證狀態，亦唔取代官方 API 排錯。綁定 MINI App 操作嘅交易通知要用 LINE 官方路徑。

UnifyPort 適合另一項獨立需求：接收已連接 LINE 帳號嘅一般客戶訊息。支援嘅 inbound 訊息會以標準化 message.received event送達。Webhook endpoint 設定 signing_secret 後，delivery 會帶 X-Device-Timestamp 同 X-Device-Signature；routing 前要用 raw body 驗證 HMAC-SHA256。

兩套 state machine 要保持分離：service notification token 屬於 MINI App 交易流程，客戶回覆屬於客服訊息流程。用自己系統嘅 order 或 reservation ID 關聯，唔好重用平台 token。

限制同取捨

當認證 MINI App 要傳送已批准嘅確認、結果或提醒，官方 Service Message API 先係正確選擇。非官方介面無法提供平台原生 template、身份同政策控制。

非官方介面亦唔可以移除 LINE 資格規則、恢復過期 token、增加五則訊息限制，或者將客服回覆變成 service message；佢只負責經統一 inbound API 傳遞受支援一般對話。

FAQ

點解未到期 LIFF access token 會回傳 401？

用戶關閉 LIFF app 後，LINE 可能撤銷 token。請由新 LIFF session 取得 token，並只 exchange 一次。

點解 token 簽發成功，send 仍回傳 403？

兩個 endpoint 檢查唔同。send call 可能因 channel 冇該環境權限，或 templateName 不存在而失敗。

timeout 後可以重送 service message 嗎？

唔好盲目重送。response 遺失時，訊息同 token 狀態可能已改變；應先對帳。

事故 log 應保存乜嘢？

保存時間、method、endpoint、status、脫敏 response、channel/環境、template 名、job ID 同安全 token fingerprint；實際 token 只放受保護儲存。

200 中兩個計數都係 0 代表乜？

訊息已傳送，但 LINE 無法更新 notification token。請標記成功，唔好再用該 token。

下一步

按官方 LINE MINI App API reference建立 status dispatcher，發布前替兩個 endpoint 各測試一次受控失敗。如果另一需求係一般 LINE 客服訊息，等官方通知流程穩定後再睇 UnifyPort LINE 授權指南。

資料來源

以下 LINE 官方來源核對於 2026-08-06：