Idempotency — Xulo Docs

A network error can leave you unsure whether a call went through. Send an Idempotency-Key header, or an idempotency_key field in the body, and retry with the same key.

Shell
curl https://api.xulo.io/api/v1/notifications \
  -H "Authorization: Key $XULO_REST_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042-shipped" \
  -d '{
    "app_id": "YOUR_APP_ID",
    "contents": {"en": "Your order shipped"},
    "include_external_ids": ["USER_ID"]
  }'

The same key in the body:

JSON
{
  "app_id": "YOUR_APP_ID",
  "contents": {"en": "Your order shipped"},
  "include_external_ids": ["USER_ID"],
  "idempotency_key": "order-1042-shipped"
}

If you send both, they must be the same. Otherwise the call returns 422 with "The Idempotency-Key header and idempotency_key differ. Send one key."

How it works

The first call with a key sends, and Xulo keeps the key with that send for 24 hours.
A repeat with the same key and the same body on the same app does not send again. It returns the first response, with the same status code and body, and the header Idempotent-Replay: true.
A segment or tag send replays its first 202 with status: "queued", not its progress. Read the progress with Notification stats.
The same key with a different body returns 422 with "This idempotency key was already used with a different request." The order of fields in an object does not matter. The order of items in a list does.
While the first call with a key is still being handled, a repeat waits up to 5 seconds for it. If it is still not done, the repeat returns 409 with Retry-After: 1 and "A request with this idempotency key is still in progress. Retry in a moment." Nothing is sent. Retry with the same key.
After 24 hours the key is free again. A call with it is a new send.
Keys are per app. The same key on two apps is two sends.
A repeat counts against the rate limits like any other call.

The key

Up to 80 characters: letters, numbers, underscore, dot and dash. Anything else returns 422 with "Use a short idempotency key: letters, numbers, dot, or dash." In the body, the key must be a string, or the call returns 422 with "idempotency_key is a string."

Use a value tied to the event that causes the push, such as an order id and a step, so that every retry of that event sends the same key.

How it works#

The key#

How it works

The key