Idempotency
Your connection dropped. Did the waiver send?
You cannot tell a lost response from a lost request, so every write that
creates something takes an Idempotency-Key header — your own key,
8 to 255 characters, one per logical operation.
Idempotency-Key: 7d3f9e2a-…The semantics are Stripe's, deliberately, because you should not have to read our documentation to find out we were creative:
| You send | We answer |
|---|---|
| A key never seen before | Do the work, and store the response under the key. |
| The same key, the same body | The stored response, without doing the work again. |
| The same key, a different body | 409 conflict. Refused, never absorbed. |
| The same key while the first is still running | 409, and try again shortly. |
| The same key after a failure | Do the work. A failure is retried, not replayed. |
The third row is the one worth arguing about. Returning the first response to a materially different request would be worse than an error: you would believe your second request happened, and it did not. So the request is fingerprinted, and a key reused across different bodies is reported. That is a bug in the caller, and a bug found loudly on the first test run is a kindness.
Keys live 24 hours — long enough for any retry a sane client makes, and no longer. The body itself is never stored; only a hash of it, so comparing two requests does not mean keeping somebody's name and address in a cache for a day to solve a plumbing problem.
Reads take no key. PUT /v1/subjects takes none either: it is
keyed on (provider, external_id), so importing the same
reservation twice is one reservation and a key would be belt on braces.
Ready to build? An API key takes a minute in the portal, and the free plan covers the first 25 agreements a month.
Get an API key