LINE MINI App Service Message API Errors: 400, 401, 403, 429, and 500 Runbook
A LINE MINI App Service Message API error is easiest to diagnose by identifying which call failed: token issuance or message sending. Treat 400, 401, and 403 as configuration or state errors, slow down after 429, and investigate 500 before retrying. On every successful send, persist the renewed notification token before another worker can use the old value.
Key takeaways
POST /message/v3/notifier/tokenandPOST /message/v3/notifier/send?target=servicecan return the same status for different reasons, so log the operation as well as the status.- A LIFF access token can be invalidated when the user closes the LIFF app, even before its stated expiry.
- A successful send normally renews the service notification token; save the returned value atomically with
remainingCountandexpiresIn. 429is a signal to reduce request volume, not to start a tighter retry loop. LINE explicitly says not to load-test against the platform.- Do not blindly replay an uncertain send. The Service Message API reference does not document an idempotency key for this endpoint.
LINE MINI App Service Message API error table
LINE’s official API reference documents two server-side calls. The token endpoint exchanges one LIFF access token for a user-bound service notification token. The send endpoint combines that notification token with an approved template.
| Status | Token issuance | Message sending | First check |
|---|---|---|---|
400 Bad Request | Invalid body, or the same LIFF access token was reused to issue tokens in a short period | Invalid body, invalid template parameters, or target recipient does not exist | Validate the exact request for the failing endpoint |
401 Unauthorized | Channel access token or LIFF access token is invalid | Channel access token or service notification token is invalid | Identify which token belongs to this operation; never swap token types |
403 Forbidden | Channel is not authorized to issue service messages | Channel is not authorized, or templateName cannot be found | Check verified/developing channel status and template deployment |
429 Too Many Requests | Request rate exceeded | Request rate exceeded | Stop synthetic traffic, apply backoff, and reduce concurrency |
500 Internal Server Error | Documented as an internal server error | If a send returns 5xx, treat it as an operational incident; the send-specific table does not list 500 | Preserve evidence, check LINE notices, then retry cautiously |
This table is a dispatcher, not a substitute for the response body. Store the status, endpoint, request time, redacted response body, channel/environment identifier, template name, and your own job ID. Keep access tokens and notification tokens in a secret store; use a one-way fingerprint in application logs so operators can correlate a failure without exposing credentials.
Runbook: diagnose the failing state before retrying
1. Separate token issuance from message sending
For issuance, verify that the browser obtained the LIFF access token for the current session and sent it once to your backend. Do not call the Service Message API from the browser because the request also requires a channel access token. LINE allows only one service notification token to be issued from one LIFF access token.
For sending, verify all three inputs independently: the channel access token, the current service notification token, and templateName with its supported BCP 47 suffix such as _ja, _en, _zh-TW, or _th. A valid token cannot compensate for a template that is missing from the channel.
The notification-token tutorial covers the normal two-call flow. Use this runbook only after you can name the call that failed.
2. Handle 400 as an endpoint-specific validation failure
On token issuance, check whether the same LIFF access token was submitted twice, perhaps because a button fired twice or a frontend retry repeated a completed request. On message sending, compare params with the approved template and enforce its character limits before dispatch. LINE notes that a value beyond a template’s hard limit cannot be sent.
Do not solve a 400 by rotating every credential. Fix the request or user state, then create a new business operation with its own job ID. The template-review checklist is the right place to verify template variables and links before production.
3. Handle 401 by tracing token ownership and lifetime
Record which token class failed without recording the token value:
- Channel access token: authorizes the MINI App channel; LINE recommends stateless or short-lived channel access tokens for MINI App channels.
- LIFF access token: proves the current user session for token issuance and may be revoked when the LIFF app closes.
- Service notification token: belongs to one user and cannot be transferred to another user.
If the user closed the app before your backend exchanged the LIFF access token, reopen the flow and obtain a fresh LIFF token. If sending failed, confirm that the worker loaded the latest renewed notification token rather than an older value from a queue snapshot.
4. Handle 403 as an authorization or deployment mismatch
A 403 during issuance means the channel cannot issue service messages. A 403 during sending can also mean the requested template is unavailable. Confirm that the call is using the intended Developing or Published channel, that production eligibility is satisfied, and that the template is reflected for that channel and locale.
Changing an app from unverified to verified does not repair an incorrect template name. Conversely, a correct template does not grant an unverified Published channel production access. The verified-versus-unverified guide keeps those two checks separate.
5. Serialize renewed notification-token writes
LINE renews the service notification token after a successful send while it still has life and remaining message count. Treat the returned token as a state transition:
load current token -> send once -> persist returned token and counters -> release next jobUse a database transaction, compare-and-set version, or per-user queue so two workers cannot send with the same old token simultaneously. If expiresIn and remainingCount are both 0, LINE says the message was sent but the token could not be renewed. Mark the send successful and stop scheduling another service message with that token.
6. Retry only when the outcome is safe to repeat
Do not retry 400, 401, or 403 until the underlying request, credential, or authorization state changes. For 429, back off with jitter and lower concurrency; do not use the production API for load testing. For an explicit 500, preserve the request record and retry through a controlled job only after checking LINE’s status or news page.
The difficult case is a timeout after dispatch, because the client may not know whether LINE accepted the message and renewed the token. Since the Service Message API reference does not document an idempotency key, a blind retry can duplicate a user-visible notification. Route uncertain outcomes to reconciliation or operator review instead of treating them as ordinary transient failures.
Where UnifyPort fits
UnifyPort does not issue LINE service notification tokens, approve MINI App templates, change verified status, or diagnose the official Service Message API. Use LINE’s official path for transactional notifications tied to a MINI App action.
UnifyPort fits the separate requirement of receiving ordinary customer messages from a connected LINE account. Supported inbound messages arrive as normalized message.received events. When a webhook endpoint has a signing_secret, delivery includes X-Device-Timestamp and X-Device-Signature; verify the HMAC-SHA256 signature against the raw body before routing the conversation.
Keep the two state machines separate. A service notification token belongs to LINE’s transactional MINI App flow; a customer reply belongs to the support-message flow. Join them in your own system with an order or reservation identifier, not by reusing platform tokens.
Limitations and trade-offs
The official Service Message API is the correct choice when a verified MINI App must send approved confirmations, results, or reminders. It supplies the platform-native template, identity, and policy controls that an unofficial interface cannot provide.
An unofficial interface cannot remove LINE’s eligibility rules, recover an expired notification token, increase the five-message allowance, or turn a support reply into a service message. Its role is narrower: deliver supported ordinary conversations through a standard inbound API.
FAQ
Why does a valid LIFF access token return 401?
LINE says a LIFF access token can be revoked when the user closes the LIFF app even if its expiry time has not passed. Obtain a fresh token from a new LIFF session and exchange it once.
Why does sending return 403 when token issuance worked?
Issuance and sending have different checks. The send call can fail because the channel is not authorized for the environment or because templateName is not available in that channel.
Can I retry a LINE service message after a timeout?
Not blindly. If the response was lost, the message may have been sent and the notification token may have changed. Because no idempotency key is documented for this endpoint, reconcile the outcome before sending again.
What should I log for a Service Message API incident?
Log request time, method, endpoint, status, redacted response, channel/environment, template name, job ID, and a safe token fingerprint. Store actual tokens only in protected credential storage.
What does remainingCount: 0 and expiresIn: 0 mean after 200?
The message was sent, but LINE could not renew the service notification token. Treat the delivery as successful and do not schedule another send with that token.
Next step
Build the status dispatcher against the official LINE MINI App API reference, then test one controlled failure for each endpoint before release. If the separate requirement is ordinary LINE customer-message intake, review the UnifyPort LINE authorization guide after the official notification flow is stable.
Sources
Official LINE sources checked on August 6, 2026: