API reference Development guidelines Quickstart Guides - Sending messages
- Character counting in a text
- Getting user IDs
- Stickers
- LINE emoji
- Use audiences
- Use quick replies
- Get statistics per aggregation unit
- Use LINE features with the LINE URL scheme
- Using beacons
- Sharing your LINE Official Account with users
- Linking user accounts
- Change icon and display name
- Get quote tokens
- Retrying a failed API request
- Stop using your LINE Official Account
- Stop using the Messaging API
- Tutorial - Make a reply bot
Webhooks Rich menus LINE Bot Designer Flex Message Concepts Reference Resources
API reference Development guidelines Quickstart Guides - Sending messages
- Character counting in a text
- Getting user IDs
- Stickers
- LINE emoji
- Use audiences
- Use quick replies
- Get statistics per aggregation unit
- Use LINE features with the LINE URL scheme
- Using beacons
- Sharing your LINE Official Account with users
- Linking user accounts
- Change icon and display name
- Get quote tokens
- Retrying a failed API request
- Stop using your LINE Official Account
- Stop using the Messaging API
- Tutorial - Make a reply bot
Webhooks Rich menus LINE Bot Designer Flex Message Concepts Reference Resources
# Retrying a failed API request
# Summary
If an error with status code 5xx occurs when sending a message using the Messaging API, or if the request times out, the message may not have been correctly delivered to users. However, if the same API request is executed in succession, users will receive the same message twice if the first API request was accepted correctly.
No matter how many times the API request containing the same value of a retry key (X-Line-Retry-Key
) is executed, since it is always accepted only once, it prevents the same process from being duplicated. If the request has already been accepted, the re-request is blocked and the status code 409
is returned.
Using a retry key, you can safely retry a request without duplicate API requests being processed.
X-Line-Retry-Key
allows you to safely retry API requests without duplicating messages, but it doesn't guarantee reliable delivery of messages. If an API request is accepted (HTTP status code 200) by the LINE Platform even once, it won't be possible to retry the same request, even if it couldn't be delivered correctly because the user has blocked the LINE Official Account.
# Flow of API request retry
If you use endpoints that can retry API requests using retry keys, use this flow to implement them.
# 1. Always specify the retry key
When using these endpoints, always specify the retry key (hexadecimal UUID generated by any method) in the X-Line-Retry-Key
request header.
Sending methods | API reference |
---|---|
Push message | Send push message |
Multicast message | Send multicast message |
Narrowcast message | Send narrowcast message |
Broadcast message | Send broadcast message |
Example of specifying a retry key (123e4567-e89b-12d3-a456-426614174000
) when sending a push message:
curl -v -X POST https://api.line.me/v2/bot/message/push \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer {CHANNEL_ACCESS_TOKEN}' \
-H 'X-Line-Retry-Key: 123e4567-e89b-12d3-a456-426614174000' \
-d '{
"messages": [
{
"type": "text",
"text": "Hello, user"
}
]
}'
API requests that don't specify X-Line-Retry-Key
can't be retried.
For APIs other than the above, retry keys cannot be specified. If you include X-Line-Retry-Key
in the request header, the API request will be rejected and the status code 400
will be returned.
# 2. Retry API requests as needed
Design how to retry an API request according to the response status code as follows.
Status code | Description | Need to retry or not |
---|---|---|
500 Internal Server Error | Internal server error. | ✅ The request may be successful by retrying. |
Timeout | The request failed due to a network failure or some other reason. | ✅ The request may be successful by retrying. |
200 status code | The API request has been accepted. | ❌ Additional retries won't be accepted. |
409 Conflict | An API request with the same retry key has already been accepted. | ❌ The request has already been accepted. |
4xx | Problem with the request. | ❌ Trying again does not change the results. |
- The retry key is valid for 24 hours after attempting the first request. The request retries using the retry key should be designed to run within 24 hours.
- All requests using the same retry key should have exactly the same content. The behavior is not guaranteed if the same retry key is used to send a message with different contents or to a different destination.
- Since retries using retry keys are counted in the API request count, frequent retries may cause the API rate limit to be reached.
- We recommend you to control the retry interval by exponential backoff (opens new window).
# Response when API request is retried
The response depends on whether the API request has been accepted.
If multiple requests including the same retry key are executed, each request will be assigned a different request ID.
# Example response to a request that has been accepted
This response is the same as the response when no retry key is specified.
HTTP/1.1 200 OK
x-line-request-id: 123e4567-e89b-12d3-a456-426655440001
# Example response when retrying a request that has been accepted once
If an API request including a retry key has already been accepted, the status code 409
and the request ID of the accepted request will be included in the response header as x-line-accepted-request-id
.
HTTP/1.1 409 Conflict
x-line-request-id: 123e4567-e89b-12d3-a456-426655440002
x-line-accepted-request-id: 123e4567-e89b-12d3-a456-426655440001
{
"message": "The retry key is already accepted"
}
Furthermore, in the case of push messages, a JSON object that includes the same sentMessages.id
and sentMessages.quoteToken
as when the API request was accepted will be returned.
HTTP/1.1 409 Conflict
x-line-request-id: 123e4567-e89b-12d3-a456-426655440002
x-line-accepted-request-id: 123e4567-e89b-12d3-a456-426655440001
{
"message": "The retry key is already accepted",
"sentMessages": [
{
"id": "461230966842064897",
"quoteToken": "IStG5h1Tz7b..."
}
]
}
# Related pages
- "Retrying an API request" section in the Messaging API reference