Idempotency

Networks fail after the server has already done the work. Retrying then would create a second record, so writes can be made safely repeatable.

Writes addressed by external id

PUT /v1/members/external/{source}/{external_id} is already idempotent — the external id is the identity, so sending it twice updates the same person. No header needed.

Everything else

Send Idempotency-Key with a value unique to that attempt (a UUID is fine) and reuse it on every retry of the same request.

curl -X POST https://api.theskillsfest.com/v1/members \
  -H "Authorization: Bearer $SKILLSFEST_KEY" \
  -H "Idempotency-Key: 6b1f0a9c-1f3a-4b7e-9d2b-8f1a0c3d5e7f" \
  -H "Content-Type: application/json" \
  -d '{ "first_name": "Ada", "last_name": "Lovelace", "role": "Student" }'

• Same key, same request → the original response, with Idempotency-Replayed: true.
• Same key, still in flight → 409 idempotency_in_progress. Wait and retry.
• Same key, different body → 422 idempotency_key_reuse. We refuse loudly rather than returning someone else’s result.

Keys are scoped to your API key and kept for 24 hours.