Idempotency

Networks fail after the server has acted but before you see the response. An Idempotency-Key makes the retry safe: SalesOS runs the request once and replays the original response to every retry.

curl -X POST https://api.salesos.org/v1/opportunities \
  -H "X-API-Key: $SALESOS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 9b2f6c1e-3c1d-4a0e-9d55-2d8f0c7d1a42" \
  -d '{"name":"Acme renewal","accountId":"clx...","amount":48000}'

Rules

Supported on POST and PATCH, for API keys and session tokens.
Use a new random key (a UUID v4) for each logical operation, and reuse it only to retry that operation.
Keys are scoped to your organization and kept for 24 hours.
A key is 1–255 visible ASCII characters; anything else is 400 IDEMPOTENCY_KEY_INVALID.

What happens on a retry

Situation	Response
Original finished	The original status and body, plus `Idempotent-Replayed: true`. The handler does not run again
Original still running	`409 IDEMPOTENCY_REQUEST_IN_PROGRESS` with `Retry-After: 1`
Same key, different method, path, body or credential	`409 IDEMPOTENCY_KEY_REUSED`
Original failed (any error)	The key is released, so the retry runs normally
Original response was too large to store (over 512 KB)	`409 IDEMPOTENCY_RESPONSE_UNAVAILABLE`. The original succeeded; read the result instead

The comparison is of the method, path, query string and JSON body. Object key order doesn't matter.

Not covered

Idempotency keys are ignored on file uploads, streaming responses and endpoints that return secrets (API key creation and rotation). Retrying those is never deduplicated.

Rules

What happens on a retry

Not covered

On this page