Skip to content
Fedwright developers

This is the staging environment's documentation. It is a draft and may change at any time.

Idempotency

A network failure can leave you not knowing whether a POST that creates something went through. The Idempotency-Key header lets you send it again without creating a second copy.

Which operations take a key

Section titled “Which operations take a key”

An operation that creates something takes an Idempotency-Key, and requires it. Each operation’s reference lists the header. Among the operations a machine client can call, createSavedSearch is one. Others, such as createOrganization and createMachineClient, are for signed-in users.

Operations that don’t take the header ignore it.

The key

Section titled “The key”
Rule Detail
Length 8 to 255 characters
Value Your choice. A random UUID for each new request is a good one.
Required A missing key, or one outside the length bounds, is refused with 400 (bad-request).

Make one key for each thing you intend to do. Use the same key only to retry that same request.

What the API does

Section titled “What the API does”

The API keeps a key for one caller (a user, a machine client, or a service identity), one operation, and the acting organization where there is one. The same key sent for another operation or by another client is a different key.

Situation Answer
First request with this key The operation runs, and its answer is returned.
The same request again, after the first finished The first answer again: its status, body, and Location and ETag. It carries Idempotent-Replayed: true.
The same key with a different request 422 with the Problem type idempotency-key-reused.
The same key while the first request is still running 409 with idempotency-in-progress and Retry-After.
  • “The same request” means the same method, path, and body.
  • A replay is available for 24 hours after the first request completes. After that, the key can be used again.
  • Only a successful response is kept. A request the API refuses (for a bad body, a missing scope, a conflict, or a rate limit) keeps nothing, so you can fix it and send it again with the same key, or with a new one.
  • If the first request is still running, the API may wait a short time for it to finish before it answers 409. Retry after Retry-After seconds with the same key. The retry returns the first answer once it exists.

Example

Section titled “Example”
Create a saved search, then retry it safely
API_BASE='https://api-staging.fedwright.com/v1'
ORG_ID='YOUR_ORGANIZATION_ID'
key=$(uuidgen)


for attempt in 1 2; do
  curl -sS -i "$API_BASE/orgs/$ORG_ID/saved-searches" \
    -H "Authorization: Bearer $token" \
    -H "Idempotency-Key: $key" \
    -H 'Content-Type: application/json' \
    -d '{"name": "Step assemblies", "alerting": false, "query": {"q": "step assy"}}'
done

The second answer is identical to the first, with one more header:

HTTP/1.1 201 Created
Idempotent-Replayed: true
Location: ...
ETag: "..."

This call needs the searches:write scope.

Retrying

Section titled “Retrying”
  • Reuse the key when you retry after a timeout, a dropped connection, a 502, 503, or 504, or a 409 idempotency-in-progress.
  • After a 429, wait as Rate limits says, then send the request again. The 429 came before the operation ran.
  • Don’t reuse a key for a changed request. Make a new key.
  • Don’t treat Idempotent-Replayed: true as an error. It says the answer is the first one, and that nothing was created a second time.