Idempotency

Every POST endpoint accepts an Idempotency-Key header. Retrying with the same key returns the original result rather than creating a second resource. This matters most for the failure you cannot see: a request that reached the server, succeeded, and then timed out on the way back. Without a key, the safe-looking retry creates a duplicate submission.

curl -X POST http://localhost:3000/v1/submissions \
  -H "Authorization: Bearer $MONEYLINE_API_KEY" \
  -H "Idempotency-Key: deal-001-create" \
  -H "Content-Type: application/json" \
  -d '{"external_id": "deal-001"}'

await client.submissions.create(
  { external_id: 'deal-001' },
  { idempotencyKey: 'deal-001-create' },
);

client.submissions.create(
    external_id="deal-001",
    idempotency_key="deal-001-create",
)

Choosing a key

A good key is derived from the thing you are creating, not from the moment you are creating it.

deal-001-create — derived from your own identifier for the deal.

A UUID generated once and stored alongside the pending write.

A fresh UUID per attempt. Every retry looks like a new request, which defeats the purpose.

Keys are scoped per organization and per endpoint. The same key on POST /v1/submissions and POST /v1/webhooks refers to two different operations and will not collide.

Interaction with retries

The SDKs retry 429 and 5xx automatically. When you supply an idempotency key those built-in retries are safe by construction — which is the reason to always supply one on writes.

Get started

Guides

Tools

Choosing a key

Interaction with retries

​Choosing a key

​Interaction with retries

Choosing a key

Interaction with retries