Safe retries

If a request times out, you can't tell whether it took effect. Idempotency-Key lets you retry without creating the same thing twice.

These operations accept it:

• POST /orgs/{org_id}/projects
• POST /orgs/{org_id}/invitations
• POST /orgs/{org_id}/projects/{project_id}/quota_increase_requests

Send a unique value of up to 255 characters, and reuse it only to retry that same request. A UUID works well:

KEY=$(uuidgen)

curl -s -X POST "$BASE/orgs/$ORG_ID/projects" \
  -H "Authorization: Bearer $BREQWATR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $KEY" \
  -d '{"name": "web"}'

What a retry does

Situation	Response
Same key and same request, after it succeeded	The original response, with Idempotent-Replayed: true. Nothing is created again
Same key and same request, while the first is still running	409 idempotency_key_in_progress. Retry shortly
Same key and a different request	422 idempotency_key_reused. Use a new key
Same key, after the first request failed	The request runs again. Failures aren't stored
A key over 255 characters	400 bad_request

Successful responses are kept for 24 hours. After that, the same key runs the request again. Keys belong to the API key that sent them, so two API keys can use the same value independently.

Without the header, each request runs on its own, and a retry can create a duplicate.