LINE X-Line-Retry-Key: Retry Timed-Out Sends Without Duplicates
For supported LINE Messaging API sends, put X-Line-Retry-Key on the first request, then reuse that key with the same recipient and content after a timeout or retryable server failure. Generate a hexadecimal UUID for each new logical request. A retry returning 409 because that key was already accepted means stop—not generate another key. This prevents duplicate acceptance within the documented retry window; it does not guarantee delivery to the user.
Key takeaways
- Push, multicast, narrowcast, and broadcast support retry keys; do not apply this contract to every LINE API.
- Persist the key and original request before dispatch, not after an error.
- LINE documents a key lifetime of 24 hours after the first request.
- Separate request acceptance, recipient delivery, and inbound webhook acknowledgement.
What X-Line-Retry-Key protects
A timeout leaves an ambiguous result: your application did not receive a response, but LINE may already have accepted the send. Generating a fresh key for every attempt turns that uncertainty into another independent request.
LINE’s retry guide describes a different contract: once a request with a key is accepted, later attempts with that key are rejected as duplicates. The key must be present from the first attempt. Adding one only after an unkeyed request times out cannot retroactively protect the original send.
| Sending method | Retry-key support documented by LINE |
|---|---|
| Push | Yes |
| Multicast | Yes |
| Narrowcast | Yes |
| Broadcast | Yes |
| Other APIs, including reply messages | Not covered by this supported list; do not attach the header indiscriminately |
LINE says attaching the header to an unsupported API results in 400. This is also not the LINE MINI App notification-token workflow. For that separate surface, use the Service Message API error runbook, not this retry-key procedure.
Build the retry record before the network call
The following is a recommended application design, not additional LINE API fields.
Create a durable outbound record containing your business operation identifier, channel identity, sending method, exact request body, retry UUID, first-attempt time, retry deadline, and processing state. Protect recipient data and message content according to your retention policy. Keep access tokens out of the record and ordinary logs; load credentials from protected configuration.
Persist that record before dispatch. Every retry must load the saved key and request rather than reconstructing a message from mutable order or customer data. LINE explicitly says not to change either the content or recipient when reusing a key.
Use a unique application operation identifier and a worker claim or lock. Otherwise, two workers can create different UUIDs for the same business action, and both requests can be accepted. A retry key deduplicates the keyed request; it does not discover that two separately created jobs meant the same thing.
If several tools share your Official Account, define which system owns each outbound action. The multiple-tools checklist covers the shared-channel boundary; a local outbox adds ownership of individual sends.
Decide from the actual outcome
Follow LINE’s status-based retry guidance. Do not treat every non-success response as permission to resend.
| Observed outcome | Recommended worker action |
|---|---|
2xx | Record acceptance and stop retrying |
| Timeout or retryable server failure | Schedule a bounded retry with the original key and unchanged request |
409 indicating that the key was already accepted | Record prior acceptance; preserve x-line-accepted-request-id; stop |
Other 4xx | Stop the unchanged retry loop and investigate the request or restriction |
| Retry window exhausted with no known acceptance | Hold for reconciliation or operator review, rather than silently generating a new key |
For a duplicate-acceptance response, LINE returns x-line-accepted-request-id to identify the successful request. Keep that separate from x-line-request-id, which identifies an individual request attempt. Preserve status, timestamps, and redacted diagnostics; do not branch on an error-message string alone.
LINE recommends exponential backoff and notes that retries count toward API rate limits. Your scheduler should impose its own attempt budget and never schedule beyond the key’s 24-hour validity. That is a lifetime from the first request, not a fresh 24 hours after every retry. A conservative application deadline may be earlier.
After expiry, an unknown result remains unknown. A new key represents a new sending decision and can duplicate an earlier accepted message. Require explicit reconciliation or approval rather than treating key replacement as routine recovery.
Acceptance is not delivery
LINE explicitly warns that retry keys do not guarantee reliable recipient delivery. For example, acceptance does not ensure delivery to someone who blocked the Official Account. Once accepted, repeatedly submitting the same keyed request is not a delivery-repair mechanism.
Keep your application state precise: “accepted by LINE” is not “read by the customer.” Similarly, an HTTP success returned by your own webhook receiver only acknowledges inbound delivery. It does not confirm an outbound message was sent.
Keep the UnifyPort contract separate
UnifyPort’s unofficial interface connects messaging accounts and delivers normalized events such as message.received. It is not another sender inside the same LINE Official Account Messaging API channel, and its public send reference does not document support for X-Line-Retry-Key.
For UnifyPort, consult the text-message contract before implementing outbound retries. Do not import LINE’s 24-hour key lifetime or duplicate-acceptance response into that integration. A tracing identifier is not automatically an idempotency guarantee.
For inbound traffic, enable signing_secret and verify X-Device-Signature as HMAC-SHA256 over X-Device-Timestamp, a dot, and the raw body. Follow the webhook delivery reference for acknowledgement and retry behavior. Incoming-event deduplication and outgoing-send deduplication solve different problems; implementing one does not supply the other.
Use the official Messaging API when you require its Official Account sending features. Choosing an ordinary-account interface does not repair an uncertain send already made through the official API.
FAQ
Can I create the retry key after the first timeout?
Not to protect the original request. The key must be included from the first attempt on a supported API.
Does 409 mean I should send again with a new UUID?
Not when it indicates that the same key was already accepted. Save the accepted request ID and stop retrying that operation.
Can I change the recipient while retaining the key?
No. LINE says retried content and recipient must match the original request. A changed business action needs a separate decision, not a mutated retry.
Does this work for every LINE message API?
No. Use it only on the documented supported methods. Do not transfer this contract to MINI App service messages or UnifyPort sends.
Next step and sources
Review one outbound worker: can it recover the same key and same request after a crash? Test that boundary with a local mock before exercising a controlled supported send. For the separate connected-account path, review the UnifyPort send reference.
Official references checked on 2026-09-28:
Turn messaging integration into a stable product pipeline.
Start by sending through one API, then bring every inbound message back into your business system with standard events.