Idempotency - Spritz

Money-moving requests should be safe to retry. If a request times out or your connection drops mid-flight, you often can’t tell whether it went through. Send an idempotency key and Spritz guarantees the operation runs at most once. A retry with the same key returns the original result instead of doing the work again.

Send an idempotency key

Add an Idempotency-Key header, a unique value such as a UUID, to any mutating request (POST, PUT, PATCH, DELETE). Reuse the same key when you retry that request.

curl -X POST https://platform.spritz.finance/v1/off-ramp-quotes/ \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 3f9a1c2e-8b47-4d6a-9c1f-2b7e5a0d4e11" \
  # plus your integrator signing headers and the user's Authorization (see Authentication)
  -d '{ "accountId": "...", "amount": "100.00", "rail": "ach_standard", "chain": "ethereum" }'

Idempotency applies to authenticated mutating requests that include the header. GET requests are already safe to repeat, so they don’t need a key.

What happens on a retry

Situation	Result
First request with a new key	Processed normally, and the response is stored for 24 hours
Same key and same request, after it finished	You get the original response back, with the header `X-Idempotency-Replayed: true`. The operation does not run again
Same key while the first request is still processing	`409` (`urn:problem-type:request-in-progress`). Wait and retry; a `Retry-After` header tells you how long
Same key but a different request body	`422` (`urn:problem-type:idempotency-conflict`). A key is bound to one exact request

Scope and lifetime

A key is bound to your auth context and the exact request (method, path, and body). If you send the same key with a different body, Spritz rejects it with a 422 rather than risk returning the wrong result. Keys are remembered for 24 hours; after that, the same key is treated as new.

Error responses

{
  "type": "urn:problem-type:request-in-progress",
  "title": "Request In Progress",
  "status": 409,
  "detail": "A request with this idempotency key is currently being processed"
}

{
  "type": "urn:problem-type:idempotency-conflict",
  "title": "Idempotency Key Conflict",
  "status": 422,
  "detail": "The provided idempotency key has been used with a different request"
}

Both are standard problem responses.

Best practices

Generate a unique key per operation, for example a UUID.
Reuse the same key when you retry the same operation, so the retry is deduplicated.
Never reuse a key for a different operation.
Persist the key until you’ve confirmed the outcome, so a crash and retry uses the same key.