Idempotency

A POST that timed out is the one call you cannot safely repeat: the connection dropped, and nothing in the response tells you whether the work happened. request_id — any string you choose, per attempt — turns that repeat into a replay.

Code
signup=$(curl_json -X POST "$SITE_API/site-api/v1/users" \
  -d "$(jq -n \
    --arg email "$EMAIL" --arg password "$PASSWORD" --arg website "$WEBSITE_NAME" \
    --arg captcha "$RECAPTCHA_TOKEN" --arg request_id "quickstart-$(date +%s)-$$" \
    '{email: $email, password: $password, website_name: $website,
      default_language: "en", recaptcha_token: $captcha, request_id: $request_id}')")

signup_token=$(jq -r '.signup_token' <<<"$signup")

Send the same value again within the retention window and you get the first attempt's result, not a second site. Generate it before the first try, keep it with whatever you are retrying, and change it only when you genuinely mean "do this again".

Which calls accept one is in the reference, on the request body — it is the calls where doing the work twice costs somebody something: provisioning, invitations, mail.

15. Idempotency (AIP-155)

Create and any mutating custom method MAY accept request_id (a client-chosen UUID). A repeat within the retention window (24 h) returns the original result instead of acting again. Required for anything that provisions, sends mail, or charges — signup, invitations, provisioning kick-off.

The key lives on the record the work is tracked by — on the Operation (§17) where the work has no resource of its own, and on that resource where it has one (ai_execution.request_id). Most kick-offs that need idempotency hand work off and already mint an Operation, so keying replay off that record is one mechanism instead of one bespoke field per entry point; where the call instead creates the resource the work is — one that carries its own state, is cancelled and retried by its own custom methods and is listed as history — that resource is minted before any of the work, and a second Operation beside it would be a second description of one lifecycle. Either way the key is written before the work it protects, so a call that dies half-way still leaves the retry something to find. The column is unique, so a second call that arrives while the first is still in flight loses the insert and is answered ABORTED: retry, and the retry takes the replay path.

request_id is INPUT_ONLY on the kick-off and appears in no response.