Idempotent retries

How it works

Send an Idempotency-Key header — 1 to 100 printable ASCII characters, a UUID is ideal — and reuse the same value for every retry of that one change. Endpoints that support it show an Idempotency-Key badge in the API reference.

curl -s -X POST https://console.botgg.app/api/v1/guilds/123456789012345678/bank/members/876543210987654321/transactions \
  -H "Authorization: Bearer $BOTGG_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 5f0c6a2e-8d4b-4c1e-9a7f-2b3c4d5e6f70" \
  -d '{"type":"add","amount":100,"reason":"Tournament prize"}'

• Successful responses are stored for 24 hours per API key. Retrying with the same key and the same request returns the original response — same status and body, plus the Idempotent-Replayed: true header — without changing anything again.
• The same key with a different body, member or path fails with 422 IDEMPOTENCY_KEY_REUSED.
• Failed requests (4xx and 5xx) are not stored, so you can fix the problem and retry with the same key.
• Two requests with the same key at the same time are safe too: the second waits for the first and then gets its stored response.
• Without the header, a retried request is a new change.

HTTP/1.1 201 Created
Idempotent-Replayed: true

{ "transactionId": 98765, "balance": 1350, ... }

HTTP/1.1 422 Unprocessable Entity

{ "error": "IDEMPOTENCY_KEY_REUSED", "message": "This Idempotency-Key was already used with a different request" }

In practice

1. Generate the key once per logical operation (for example per tournament payout), before the first attempt.
2. Keep it with the operation in your own database if a retry can happen after a restart.
3. On a timeout, a network error, 429, 500 or 503, send exactly the same request again with the same key.
4. Use a new key for the next, different operation.