Retrying a failed API request

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

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 API request retry

If you use endpoints that can retry API requests using retry keys, use this flow to implement them.

Retry API Request Flowchart

# 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"
        }
    ]
}'
Specify the retry key from the first API request

API requests that don't specify X-Line-Retry-Key can't be retried.

For APIs other than the above

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.
Note
  • 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.
The interval between retries
  • 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.

Request ID is different for each request

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