Retry failed API requests

# Retry failed API requests

Your message may fail to be delivered and in that case, you'll get a 5xx error or request time out. But even if you get such error, there is a possibility that your message was delivered. So, if you send the same request again because of the error, the recipient may receive the same message twice, as illustrated below:

To avoid sending the same message twice, use the retry key (X-Line-Retry-Key). If you specify the retry key, the request is executed only once, no matter how many times you make the request. Once the request is accepted, subsequent retried requests are blocked and you'll get the status code 409.

So we recommend that you use the retry key when you make retries, to prevent duplicated execution of the same API request.

Note

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 retrying API requests

To use the APIs that support retry keys, make your request in the flow illustrated below:

Retry API Request Flowchart

# Specify the retry key always

At all times, specify the retry key, X-Line-Retry-Key, in the request header when you send a message using the APIs that support retry keys. The retry key shall be a hexadecimal UUID generated by a method of your choice.

Specify the retry key in the first API request

API requests without X-Line-Retry-Key can never be retried. Make sure you add the key the first time you make the request.

The APIs that support retry are:

Sending methods API reference
Push messages Send push message
Multicast messages Send multicast message
Narrowcast messages Send narrowcast message
Broadcast messages Send broadcast message
Retry only with supported APIs

If you specify X-Line-Retry-Key in the request header of the APIs not listed above, your request is rejected and you'll get the status code 400.

Here is an example request to send a push message, with a retry key (123e4567-e89b-12d3-a456-426614174000):

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

# Retry API requests by status code

Determine whether to retry an API request by the status code you get:

Status code Description Retry or not
500 Internal Server Error Internal server error ✅ Retry. Your next request may be successful.
Timeout The request failed due to a network failure or some other reason. ✅ Retry. Your next request may be successful.
2xx The API request is accepted. ❌ Don't retry. Additional retries aren't accepted.
409 Conflict An API request with the same retry key is already accepted. ❌ Don't retry. The retried request is already accepted.
4xx Problem with the request ❌ Don't retry. Retries don't change the result.
Note
  • A retry key is valid for 24 hours after the first request. Design your service to retry requests within 24 hours.
  • Make your retried request the same as the original request. Don't change the content or the recipient. If you make a change but use the same retry key, retry may not work as you expect.
Interval between retries
  • A retry with a retry key is counted as one API request, so frequent retries may cause the API rate limit to be reached.
  • To keep the load low when servers or networks go down, we recommend that you keep the retry interval by exponential backoff (opens new window).

# Retry responses

What you receive for your retried API request differs, depending on whether the API request was accepted or not.

Different request ID is issued

If multiple requests with the same retry key are executed, each request gets a different request ID.

# Response to an accepted request

For a successful retry request, you'll get the same response as to the request that was accepted normally. Here is an example:

HTTP/1.1 200 OK
x-line-request-id: 123e4567-e89b-12d3-a456-426655440001
# Response to retrying an accepted request

If you retry an API request that the LINE Platform returned the status code 2xx, you'll get the status code 409. The response returns you the ID of the request, x-line-accepted-request-id, that was successful.

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..."
    }
  ]
}

For more information on making retries, see Retrying an API request in the Messaging API reference.