Guide

Idempotency

Networks fail. An Idempotency-Key header makes a POST safe to retry: if the first attempt went through, the retry gets the same answer instead of doing the work twice.

POST /v0/tenants/tq7x2m9k4ab/people
Idempotency-Key: 6f1c2b9e-3d4a-4c1e-9b8f-0a7d5e2c1b3f
Content-Type: application/json

{"email": "dana.levi@example.com"}

Rules

• Use a new random value (a UUID) per logical operation, and the same value for every retry of it.
• A key is remembered for 24 hours, per workspace, method and path.
• Same key, same body: you get the first answer again (same status, same body).
• Same key, different body: 409 idempotency-key-reuse. Nothing is done.
• Operations that honour the key show an idempotent badge in the reference. PUT, PATCH and DELETE are idempotent by nature (they set a state); repeating them is safe.

Answers that carry a secret

A few POSTs return a secret that is shown once — a connector install code, an enrollment code, a provisioning token, a webhook signing secret. Cloudraw never stores that secret for replay. A retry with the same key answers 409 already-issued (nothing new is created); if you did not receive the first answer, retry with a new key to get a new secret, and revoke the unused one if it was created.