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
| Rule | Detail |
|---|---|
| Methods | POST only. The header is ignored on other methods. |
| Key format | 1 to 255 characters: letters, digits, ., _ and -. A UUID works well. |
| Lifetime | 24 hours. |
| Scope | One key applies to one API key and one endpoint path. |
| What is saved | Successful 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
| Status | Code | Cause | What to do |
|---|---|---|---|
409 | idempotency_in_flight | The first request with this key is still running. | Wait a second and retry. |
422 | idempotency_key_reused | The 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.