# 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.

Note
  • 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.

The interval between retries

We recommend you to control the retry interval by Exponential Backoff (opens new window).

Retry API Request Flowchart

# 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
For APIs other than the above

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"
        }
    ]
}'
Note
  • 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"}