Network requests fail. Retries are correct. Double-creates are not. Every POST endpoint in the Geldstuck API accepts an Idempotency-Key header. Send the same key twice, and we’ll return the original response without creating a second resource.

​
How it works

1

Generate a unique key

A UUIDv4 is the safest default. Store it alongside the operation you’re about to perform.
2

Send it as a header

Idempotency-Key: 7b52c2d8-4c2e-4a51-b7d8-ac2f4b3e8b21
3

Retry freely

If the request times out, retry with the same key. We recognize it and replay the cached response.

​
Behavior guarantees

  • Keys are scoped per tenant. Reusing a key across tenants is safe.
  • Cached responses are stored for 24 hours. After that, the key is free to reuse.
  • Reusing a key with a different request body returns 409 idempotency_key_reuse.
  • The replay returns the exact original response - same status code, same body, same requestId.

​
Example

curl https://api.geldstuck.com/v1/transactions/create \
  -H "x-api-key: $GELDSTUCK_PUBLIC_KEY" \
  -H "x-api-secret: $GELDSTUCK_SECRET_KEY" \
  -H "Idempotency-Key: 7b52c2d8-4c2e-4a51-b7d8-ac2f4b3e8b21" \
  -H "Content-Type: application/json" \
  -d '{
    "accountType": "escrow",
    "title": "Vintage watch sale",
    "amount": 450000
  }'

​
Which endpoints support it?

All mutating endpoints (POST, PATCH, DELETE). GET requests are already idempotent and ignore the header.
Idempotency keys are per endpoint. A key used on POST /transactions/create is not the same as on POST /kyc, even if the string is identical.

​
What to key on

ScenarioGood idempotency key
Creating a transaction from your order system"tx:" + orderId
Adding a user from a CRM sync"user:" + crmId + ":" + nightlyJobRunId
Retrying a failed webhook-triggered actionHash of event.id
The goal: the key is deterministic from the business event, so every retry of the same business event produces the same key.