Letterby Docs

Idempotency

Retry POST requests safely with an Idempotency-Key header.

Send an Idempotency-Key header on a POST so a retry cannot run the same action twice.

Idempotency-Key: <unique string, for example a UUID>

If the connection drops and you retry with the same key and body, you get the first response back and nothing happens a second time.

Rules

RuleDetail
MethodsPOST only. The header is ignored on other methods.
Key format1 to 255 characters: letters, digits, ., _ and -. A UUID works well.
Lifetime24 hours.
ScopeOne key applies to one API key and one endpoint path.
What is savedSuccessful responses only. After an error you can retry with the same key.

A replayed response has the header Idempotent-Replayed: true.

Example

curl -X POST "https://api.letterby.com/v1/publications/$PUB_ID/offers/$OFFER_ID/accept" \
  -H "Authorization: Bearer $LETTERBY_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

Create the key once per action and reuse it for every retry of that action.

Errors

StatusCodeCauseWhat to do
409idempotency_in_flightThe first request with this key is still running.Wait a second and retry.
422idempotency_key_reusedThe key was already used with a different body, or its format is invalid.Use a new key.

Replaying POST /v1/webhooks returns signing_secret: null. The secret is only in the first response, so store it then.

On this page