チュートリアル August 6, 2026

LINEミニアプリのサービスメッセージAPIエラー対処：400・401・403・429・500

LINEミニアプリのサービスメッセージAPIエラーは、サービス通知トークンの発行とメッセージ送信のどちらで失敗したかを最初に分けると診断できます。400・401・403はrequest、token、権限の状態を修正し、429では送信量を下げます。500は証跡を残してから慎重に再試行し、送信成功時は次のworkerが動く前に更新後のnotification tokenを保存します。

要点

POST /message/v3/notifier/token と POST /message/v3/notifier/send?target=service は、同じstatusでも原因が異なるため、endpointと処理段階を一緒に記録します。
LIFF access tokenは、有効期限前でもユーザーがLIFFアプリを閉じると失効する場合があります。
送信成功時は通常service notification tokenが更新されます。返されたtoken、remainingCount、expiresInをatomicに保存します。
429は負荷を下げる合図です。短い間隔で再試行したり、本番APIへ大量のテストrequestを送ったりしないでください。
結果が不明なsendを無条件に再実行しないでください。このendpointにはidempotency keyが公式に記載されていません。

LINEミニアプリのサービスメッセージAPIエラー一覧

LINE公式のLINEミニアプリ APIリファレンスには、2つのserver-side APIがあります。token endpointはLIFF access tokenを、1人のユーザーに紐づくservice notification tokenへ交換します。send endpointは、そのtokenと審査済みtemplateを使います。

Status	token発行	メッセージ送信	最初に確認する項目
`400 Bad Request`	body不正、または同じLIFF access tokenを短時間に再利用	bodyやtemplate parameter不正、または送信先ユーザーが存在しない	失敗したendpointのrequestを検証
`401 Unauthorized`	channel access tokenまたはLIFF access tokenが無効	channel access tokenまたはservice notification tokenが無効	この処理で使うtokenの種類を特定
`403 Forbidden`	channelに発行権限がない	channelに送信権限がない、または`templateName`が見つからない	channel環境、認証、template反映状況を確認
`429 Too Many Requests`	rate超過	rate超過	テストtrafficを停止し、backoffと並列数削減
`500 Internal Server Error`	token発行の公式表にserver errorとして記載	sendで`5xx`が返る場合は運用incidentとして扱う。send専用表に`500`の記載はない	証跡を保存し、公式のお知らせを確認

この表は切り分けの入口です。response bodyも必ず確認してください。request時刻、method、endpoint、status、機密情報を除いたresponse、channelと環境、template名、自社job IDを記録します。実tokenはcredential storeだけに保存し、application logには一方向fingerprintを残すと、安全に同一tokenの問題を追跡できます。

対処手順：失敗状態を特定してから再試行する

1. token発行とメッセージ送信を分ける

発行では、現在のLIFF sessionからbrowserがtokenを取得し、backendへ1回だけ渡したか確認します。Service Message APIにはchannel access tokenも必要なため、browserから直接呼び出さないでください。1つのLIFF access tokenから発行できるservice notification tokenは1つだけです。

送信では、channel access token、最新のservice notification token、対応するBCP 47 suffix付きtemplateNameを個別に確認します。suffixは _ja、_en、_zh-TW、_thなどです。tokenが正しくても、channelにtemplateがなければ送信できません。

正常系の2-call flowはサービス通知トークンの実装ガイドにあります。どちらのcallが失敗したかを特定してから、このrunbookを使ってください。

2. `400`はendpoint固有のvalidation errorとして処理する

token発行時は、buttonの二重発火やfrontend retryで、使用済みLIFF access tokenを再送していないか確認します。送信時は、paramsを審査済みtemplateと照合し、dispatch前に文字数を検証します。LINEはhard limitを超えた値を送信できないと説明しています。

400に対して全credentialをrotateする必要はありません。requestまたはuser stateを修正し、新しいjob IDでbusiness operationを作成します。変数やPermanent linkは、production前にtemplate審査チェックリストで確認できます。

3. `401`はtokenの所有者とlifetimeを追跡する

Channel access token：MINI App channelを認証します。LINEはstatelessまたはshort-lived tokenを推奨しています。
LIFF access token：現在のuser sessionを証明し、token発行に使います。LIFFアプリを閉じると失効する場合があります。
Service notification token：1人のユーザー専用で、他のユーザーには使えません。

backendで交換する前にユーザーがアプリを閉じた場合は、LIFF flowを再度開いて新しいtokenを取得します。send側では、workerがqueue snapshot内の古い値ではなく、直前の成功responseで更新されたnotification tokenを読んでいるか確認します。

4. `403`は権限またはdeploy先の不一致として処理する

発行時の403は、channelにservice messageの発行権限がない状態です。送信時は、channel権限に加えてtemplateが見つからない場合もあります。DevelopingとPublishedのどちらを呼んでいるか、production利用条件を満たしているか、対象localeのtemplateが反映済みかを確認します。

LINEミニアプリを認証済みにしても、誤ったtemplate名は直りません。一方、正しいtemplate名でも未認証Published channelのproduction権限は得られません。認証済み・未認証の制限ガイドで2つの条件を分けて確認してください。

5. 更新されたnotification tokenを直列で保存する

送信成功後、tokenが有効で残回数があれば、LINEはservice notification tokenを更新します。responseを次のstate transitionとして扱います。

現在tokenを読む -> 1回送信 -> 返却tokenとcountを保存 -> 次jobを解放

database transaction、compare-and-set version、user単位queueのいずれかで、2つのworkerが同じ古いtokenを同時に使わないようにします。expiresInとremainingCountが両方0なら、メッセージは送信済みですがtokenを更新できなかった状態です。sendを成功として記録し、そのtokenによる次のservice messageを停止します。

6. 結果を安全に反復できる場合だけretryする

request、credential、authorization stateが変わるまで、400・401・403をretryしません。429ではjitter付きbackoffと並列数削減を行い、production APIをload testに使わないでください。明示的な500ではrequest recordを保存し、LINE status/newsを確認してからcontrolled jobで慎重にretryします。

dispatch後のtimeoutは特に注意が必要です。LINEがすでにmessageを受け取りtokenを更新したか、clientから判断できない場合があります。idempotency keyが公開されていないため、blind retryはユーザーに重複通知を届ける可能性があります。結果が不明なjobはreconciliationまたはoperator reviewへ送ります。

UnifyPortが適合する範囲

UnifyPortはLINEのservice notification tokenを発行・更新せず、MINI App templateを審査せず、認証状態を変更しません。公式Service Message APIのerrorを解消する機能でもありません。MINI App内の操作に紐づくtransaction notificationにはLINE公式APIを使います。

UnifyPortが扱うのは別の要件です。接続済みLINEアカウントの通常の顧客メッセージは、標準化されたmessage.received eventとして受信できます。Webhook endpointにsigning_secretを設定すると、deliveryにはX-Device-TimestampとX-Device-Signatureが含まれます。routing前にraw bodyでHMAC-SHA256を検証してください。

2つのstate machineは分離します。service notification tokenはMINI Appのtransaction flow、顧客からのreplyはsupport-message flowに属します。自社のorder IDやreservation IDで関連付け、platform tokenを共有しないでください。

制限とトレードオフ

認証済みMINI Appから、審査済みの確認・結果・reminderを送る場合は、公式Service Message APIが適切です。platform-native template、identity、policy controlは非公式インターフェースでは提供できません。

非公式インターフェースは、LINEの利用資格を変更せず、期限切れtokenを復旧せず、5件の送信上限を増やしません。support replyをservice messageに変換するものでもありません。役割は、対応する通常会話を共通inbound APIへ届けることです。

FAQ

有効期限前のLIFF access tokenが`401`になるのはなぜですか？

ユーザーがLIFFアプリを閉じると、期限前でもtokenが失効する場合があります。新しいLIFF sessionでtokenを取得し、1回だけ交換してください。

token発行は成功したのにsendが`403`になるのはなぜですか？

2つのendpointは確認項目が異なります。send側はchannelの環境権限、またはtemplateNameが存在しないことで失敗する場合があります。

timeout後にサービスメッセージを再送できますか？

無条件には再送しません。responseが失われた場合、message送信とtoken更新が完了している可能性があります。結果を照合してから判断します。

incident時に何をlogへ残すべきですか？

時刻、method、endpoint、status、redacted response、channel/環境、template名、job ID、安全なtoken fingerprintを残します。実tokenは保護されたstoreだけに保存します。

`200`で`remainingCount`と`expiresIn`が`0`なのは何を意味しますか？

メッセージは送信済みですが、notification tokenは更新できませんでした。成功として記録し、そのtokenを次のsendに使わないでください。

次のステップ

公式のLINEミニアプリ APIリファレンスに沿ってstatus dispatcherを実装し、release前に両endpointでcontrolled failureを1件ずつ確認してください。別要件として通常のLINE顧客メッセージを受信する場合は、公式通知flowが安定してからUnifyPort LINE認証ガイドを確認します。

参照資料

以下のLINE公式資料を2026年8月6日に確認しました。