Idempotent Requests

The API supports idempotency for safely retrying requests without accidentally performing the same operation twice. When creating an object, use an idempotency key. Then, if a network connection error occurs, you can retry the request with the same idempotency key to guarantee the same object is created no more than once.

To perform an idempotent request, provide an Idempotency-Key: <key> header on the request.

curl -L -X POST 'https://api.fullstory.com/v2/users' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Basic <API_KEY_VALUE>' \
-H 'Idempotency-Key: <KEY>'
--data-raw '{
  "uid": "xyz123",
  "display_name": "Daniel Falko",
  "email": "daniel.falko@example.com",
  "properties": {
    "pricing_plan": "paid",
    "popup_help": true,
    "total_spent": 14.55
  }
}'

Fullstory's idempotency works by saving the resulting status code and body of the response for the first request made for any given idempotency key, if the request is not considered retryable. Subsequent requests with the same key return the same result, with the exception of 429 errors or server errors above 500, which can be retried. The idempotency layer compares the incoming request body with that of the original request and errors unless they're the same to prevent accidental misuse. Results are only saved if an API endpoint started executing. If the request does not match an endpoint, or the request conflicted with another that was executing concurrently, no idempotent result is saved because no API endpoint began execution.

Creating an Idempotency Key

An idempotency key is a unique value generated by the client which the server uses to recognize subsequent retries of the same request. How you create unique keys is up to you, but we suggest using V4 UUIDs, or another random string with enough entropy to avoid collisions.

Idempotency Key Expiration

The idempotency key specified on a request will be eligible for reuse after 24 hours. Keys will be automatically removed after the 24 hour period expires. A new request is generated if a key is reused after the original has been removed.

Supported Endpoints

All create requests accept idempotency keys. Sending an idempotency key on other requests has no effect and should be avoided.