Idempotency and retries

Idempotency-Key: <key>

​

Operations that honor the key

​

Lines and hosted macOS sessions

• Replay. A request repeated with the same key, the same method, the same path and the same body within 24 hours returns the first successful response again. The body is the first one, with the trace_id and the request_id of the first request. The X-Request-Id header belongs to the new request, so it differs from request_id in the body. No header marks a replay.
• Same body. The body is compared byte for byte. A request with no body and a request with the body {} are two different requests.
• Collision. The same key with another method, path or body returns 409 idempotency_key_collision.
• In flight. While the first request is still running, a repeat returns 503 idempotency_in_flight: retry with the same key. A request that was abandoned midway frees its key after 60 seconds.
• Failures. Only a 2xx response is recorded. A request that failed leaves no trace: a retry with the same key runs again.
• Lifetime. The key is remembered for 24 hours from the request that succeeded. After that, the same request with the same key runs again: it takes or creates another line, or rents another session.
• Length. A key longer than 255 characters returns 400 validation_failed, with an issue on idempotency-key and the code too_big.

​

Messages, reactions and contact cards

• Replay. A repeated send returns 202 with the message already created, in its state at the time of the repeat: status can have moved to sent or delivered, and queue_info is null. A repeated POST of a reaction returns the entry of the first call as it is now, and does not add the reaction again: after a later DELETE, the repeat returns that entry although the reaction is removed. Read the reactions field of the message to know what is in place. When the first call added the reaction, the repeat returns 409 idempotency_conflict once a later call has changed its type. When the first call changed the type of an existing reaction, or found that type in place, iSnap does not record its key: a repeat after a later change of type changes the reaction again. A repeated DELETE returns the response of the first call. The trace_id and the request_id are new. Apart from that case, nothing is sent a second time.
• Checks before the key. On a send, the checks on the line, and with a trial key the checks on the trial, run before the key is read. A repeat returns 400 line_not_active or 403 line_suspended once the line is no longer active (403 line_not_active with a trial key), and 402 trial_needs_inbound once the trial is dormant, which the last send a trial accepts makes it. Such a refusal does not mean that the first request was refused: look for the message with GET /v1/messages.
• Same content. The content is compared after parsing: the order of the JSON fields does not matter.
• Collision. The same key on the same line with different content returns 409 idempotency_conflict. The same key with another line_id is a separate request: nothing is compared, and a new message is created. A reaction and a send share the keys of their line. A POST /v1/messages with the key of a reaction is not refused: it returns 202 with the reaction entry and sends nothing. Use a new key for every action.
• Lifetime. On a send, the key is remembered as long as its message exists: at least 72 hours from the creation of the message. Once the message is deleted, the same key creates a new message. On a reaction, the key is remembered at most until the message reacted to is deleted: the reaction entry is deleted with that message, which can be less than 72 hours after the reaction. The reaction call then returns 404 not_found, and the key can be used again on the line.
• One at a time. Send retries one after the other, not in parallel, and keep the key at 255 characters or fewer. Two simultaneous requests with one new key, or a longer key, can end in 500 internal_error. Two requests with one key never create two messages: one of them can end in 500 internal_error, and a retry with the same key then returns the message.
• Trial keys. With a trial key, the key belongs to the trial’s pool line, which other trials can share. Use keys that are unique everywhere, such as random UUIDs.

​

Attachments

​

Retrying safely

1. Generate the key before the first attempt, one per action, and store it with your own record of the action: the message to send, the line to assign.
2. Send the request. When the response does not arrive, or is a 500 or a 503, resend the same request with the same key, up to 2 times, with exponential backoff.
3. Send retries one after the other. Never send two requests with the same key at the same time.
4. To send a new message after a failed one, use a new key: iSnap never resends a failed message, and the old key returns the failed message.
5. Retry while the key is remembered: within 24 hours of the first attempt on the three line and session operations, within 72 hours on a send, and while the message reacted to exists on a reaction. Later, the key can be forgotten, and the same request to a line or session operation, or the same send, then runs again: see the row “How long the key is remembered” of Operations that honor the key.

IDEMPOTENCY_KEY=$(uuidgen) # Store it with your record of the message: reuse it to retry.

# To retry, rerun the command below with the same IDEMPOTENCY_KEY: the second request
# returns the message of the first.
curl -sS https://api.isnap.ai/v1/messages \
  -H "Authorization: Bearer $ISNAP_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -d '{
    "line_id": "line_8Xk2mQ4vTn7Bw9Rz3Lc6Yp1Hd",
    "to": "+14155550123",
    "body": "Your order has shipped."
  }'

import { randomUUID } from 'node:crypto'
import { APIError } from '@isnap/sdk'
import { client } from './isnap.js'

const idempotencyKey = randomUUID() // Store it with your record of the message: reuse it to retry.

try {
  // The SDK reuses the key on its own retries of this call.
  const message = await client.messages.send(
    {
      line_id: 'line_8Xk2mQ4vTn7Bw9Rz3Lc6Yp1Hd',
      to: '+14155550123',
      body: 'Your order has shipped.'
    },
    { idempotencyKey }
  )
  console.log(message.id, message.status)
} catch (err) {
  if (err instanceof APIError && err.code === 'idempotency_conflict') {
    console.error('The key was already used for another message on this line.')
  } else {
    throw err
  }
}

import uuid

from isnap import ISnapError, isnap_request

idempotency_key = str(uuid.uuid4())  # Store it with your record of the message: reuse it to retry.

try:
    # The helper retries a lost response, a 500 or a 503 with the same key, because a key is passed.
    message = isnap_request(
        "POST",
        "/v1/messages",
        json={
            "line_id": "line_8Xk2mQ4vTn7Bw9Rz3Lc6Yp1Hd",
            "to": "+14155550123",
            "body": "Your order has shipped.",
        },
        idempotency_key=idempotency_key,
    )
    print(message["id"], message["status"])
except ISnapError as err:
    if err.code != "idempotency_conflict":
        raise
    print("The key was already used for another message on this line.")

​

Operations that ignore the key