Idempotent requests
Retry a quote create safely with the Idempotency-Key header, and deduplicate the events Prets sends you.
A network error can leave you unsure whether a request reached Prets. Idempotency lets you retry it without doing the work twice.
Creating quotes
Create a quote is idempotent. Send a UUID you generate in the Idempotency-Key header, and send the same key again when you retry:
curl https://api.prets.app/v1/quotes \
-H "Authorization: Bearer ak_..." \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
-d '{ ... }'How Prets handles the key:
- First request. Prets creates the quote and stores the result under the key for 24 hours.
- Retry after it finished. Prets returns the stored result with
200and creates nothing new. - Retry while the first is still running. Prets returns
409with codeidempotency_in_progress. Wait a moment and retry with the same key. - Another create for the same consumer is running. Prets creates one quote per contact email at a time. A second create for the same email, even with a different key, can also return
409withidempotency_in_progress. Retry it shortly. - The first request failed. Nothing is stored, so a retry with the same key runs again.
Keys belong to your organization. Another organization using the same UUID does not collide with yours.
The key must be a UUID; anything else returns 400. A request whose body fails validation returns 422 before the key is looked at, so nothing is stored for it.
Prets does not compare the body of a retry with the original. Reusing a key with a different body returns the original quote, not a new one. Generate a new key for every new quote.
Without a key
The header is optional. If you leave it out, Prets uses a hash of the request body as the key. Sending the exact same body twice within 24 hours then returns the first quote instead of creating a second one. Send an explicit key so retries and new quotes stay under your control.
Session links
With ?session=true, Prets mints a new single-use session link on every response, including a replayed one. The quote itself is not created again.
Other endpoints
Only POST /v1/quotes reads Idempotency-Key. Other endpoints ignore it. GET requests are safe to retry.
Two other writes protect retries in their own way:
- Post a merchant message on a case: send your own
messageId. A retry with the samemessageIdand body returns the original message instead of posting it twice. The samemessageIdwith a different body returns409. - Create a case for a quote: your organization can have one open case per quote. A retry after the first create succeeded returns
409with aLocationheader that points at the open case.
Before you retry any other write, read the resource back to check whether the first attempt went through.
Events you receive
Prets expects a 2xx response to each event delivery within 30 seconds, and retries other responses with backoff for up to 24 hours. The same event can therefore arrive more than once. Every delivery of one event carries the same eventId (evt_…); use it to skip events you have already processed.