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 明確要求不要對平台發送大量測試請求。- 不要盲目重送結果不明的請求。官方 API 參考未為這個 endpoint 說明 idempotency key。
LINE MINI App Service Message API 錯誤表
LINE 官方 API 參考包含兩個 server-side 呼叫：token endpoint 用 LIFF access token 換取綁定單一使用者的 service notification token；send endpoint 用該 token 與已核准範本傳送訊息。
| 狀態 | token 簽發 | 訊息傳送 | 第一個檢查 |
|---|---|---|---|
400 Bad Request | body 無效，或短時間內重複使用同一 LIFF access token | body、範本參數無效，或目標使用者不存在 | 依失敗 endpoint 驗證實際請求 |
401 Unauthorized | channel access token 或 LIFF access token 無效 | channel access token 或 service notification token 無效 | 確認此操作使用的 token 類型 |
403 Forbidden | channel 無權簽發 | channel 無權傳送，或找不到 templateName | 檢查環境、認證狀態與範本部署 |
429 Too Many Requests | 速率超限 | 速率超限 | 停止合成流量、退避並降低並行數 |
500 Internal Server Error | 官方簽發表列為 server error | 若 send 回傳 5xx，按營運事故處理；send 專用表未列出 500 | 保存證據並查看官方通知 |
此表只用於分流，不能取代 response body。請記錄 status、endpoint、請求時間、去識別後的 response、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 教學說明正常兩次呼叫；先指出哪個呼叫失敗，再套用本文 runbook。
2. 依 endpoint 修正 400
簽發階段要檢查按鈕是否觸發兩次，或前端 retry 是否重複送出已使用的 LIFF access token。傳送階段要將 params 與核准範本逐項比對，並在 dispatch 前驗證字數限制；超過 hard limit 的值無法傳送。
不要用輪替所有憑證處理 400。修正 request 或使用者狀態，再以新 job ID 建立工作。可用範本送審清單預先驗證變數與連結。
3. 依 token 歸屬與生命週期處理 401
- Channel access token 授權 MINI App channel；LINE 建議使用 stateless 或短期 token。
- LIFF access token 證明目前使用者 session，關閉 LIFF app 時可能被撤銷。
- Service notification token 只屬於一位使用者，不能移轉。
若使用者在後端交換 token 前關閉 app，請重新開啟流程取得新 LIFF token。若傳送失敗，確認 worker 載入的是最近一次成功傳送後更新的 notification token，而非 queue snapshot 中的舊值。
4. 將 403 視為權限或部署不一致
簽發時的 403 表示 channel 無權簽發；傳送時還可能表示範本不存在。確認呼叫使用正確 Developing 或 Published channel、production 資格已滿足，且目標 locale 範本已套用。
認證 MINI App 不會修正錯誤的範本名稱；正確範本也不會讓未認證 Published channel 自動取得 production 權限。認證與未認證限制指南分開處理這兩項判斷。
5. 串行保存更新後的 notification token
成功傳送後，只要 token 還有效且有剩餘次數，LINE 會更新它。請把 response 當作狀態轉移：
讀取目前 token -> 傳送一次 -> 保存回傳 token 與計數 -> 釋放下一個工作使用 database transaction、compare-and-set 版本或 per-user queue，避免兩個 worker 同時使用舊 token。若 expiresIn 與 remainingCount 都是 0，LINE 表示訊息已傳送，但 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 審慎重試。
若 dispatch 後 timeout，client 可能不知道 LINE 是否接受訊息並更新 token。由於沒有公開的 idempotency key，盲目 retry 可能產生重複通知。請將不確定結果送入 reconciliation 或人工複核。
UnifyPort 適合的範圍
UnifyPort 不簽發 LINE service notification token、不核准 MINI App 範本、不變更認證狀態，也不取代官方 API 排錯。與 MINI App 操作綁定的交易通知應使用 LINE 官方路徑。
UnifyPort 適合另一項獨立需求：接收已連接 LINE 帳號的一般客戶訊息。支援的 inbound 訊息會以標準化 message.received 事件送達。若 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 才是正確選擇。非官方介面無法提供平台原生範本、身分與政策控制。
非官方介面也不能移除 LINE 資格規則、恢復過期 token、增加五則訊息限制，或把客服回覆轉成 service message；它只負責透過統一 inbound API 傳遞支援的一般對話。
FAQ
為什麼未到期的 LIFF access token 會回傳 401？
使用者關閉 LIFF app 後，LINE 可能撤銷 token。請從新的 LIFF session 取得 token，並只交換一次。
為什麼 token 簽發成功，傳送仍回傳 403？
兩個 endpoint 的檢查不同。send call 可能因 channel 沒有該環境權限，或 templateName 不存在而失敗。
timeout 後可以重送 service message 嗎？
不要盲目重送。response 遺失時，訊息和 token 狀態都可能已改變；應先對帳再決定。
事故日誌應保存什麼？
保存時間、method、endpoint、status、去識別 response、channel/環境、範本名、job ID 與安全 token 指紋；實際 token 只放在受保護儲存區。
200 中兩個計數都是 0 代表什麼？
訊息已傳送，但 LINE 無法更新 notification token。請標記成功，且不要再使用該 token。
下一步
依官方 LINE MINI App API 參考建立狀態分流，發布前替兩個 endpoint 各測試一次受控失敗。若另一需求是一般 LINE 客服訊息，請在官方通知流程穩定後閱讀 UnifyPort LINE 授權指南。
資料來源
以下 LINE 官方來源核對於 2026-08-06：