# Retrying a failed API request
# Summary
If an error with status code 5xx occurs when sending a reply message or push 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 does not guarantee the reliable delivery of messages. If an API request is accepted (HTTP status code 200) by the LINE platform even once, it will not be possible to retry the same request, even if it could not be delivered correctly because the user has blocked the LINE Official Account.- 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.
# Designing how to retry API requests
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. |
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. |
# Flow of API request retry
Implement so that the API request using the retry key is retried only when the status code 5xx occurs or the request times out. 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).
# APIs for which retry keys are available
Sending methods | API reference |
---|---|
Push message | Send push message |
Multicast message | Send multicast message |
Narrowcast message | Send narrowcast message |
Broadcast message | Send broadcast message |
If you include X-Line-Retry-Key
in the request header with other APIs than the above, the request will be rejected and the status code 400
will be returned.
# Request Header
Header | Description |
---|---|
X-Line-Retry-Key | Arbitrarily generated UUID in hexadecimal notation (example: 123e4567-e89b-12d3-a456-426614174000) |
# Example request
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: {UUID}' \
-d '{
"messages": [
{
"type": "text",
"text": "Hello, user"
}
]
}'
X-Line-Retry-Key
request header is valid for 24 hours after attempting the first request.- 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.
# Response
If multiple requests including the same retry key are executed, each request will be assigned a different request ID.
Also, if an API request including a retry key has already been accepted, executing a request with the same retry key will return the status code 409
and include the request ID of the accepted request in the response header as x-line-accepted-request-id
.
# Example response to a request that has been accepted
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
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"}
# Related pages
- “Retrying an API request” section of the Messaging API reference documentation