Безопасные повторные запросы

Как это работает

Передайте заголовок Idempotency-Key — от 1 до 100 печатных ASCII-символов, идеально подойдёт UUID — и используйте одно и то же значение при каждом повторе этой операции. Эндпоинты, которые его поддерживают, отмечены в справочнике значком Idempotency-Key.

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"}'

• Успешные ответы хранятся 24 часа для каждого API-ключа. Повтор с тем же ключом и тем же запросом вернёт исходный ответ (тот же статус и тело плюс заголовок Idempotent-Replayed: true), а данные второй раз не изменятся.
• Тот же ключ с другим телом, участником или путём вернёт 422 IDEMPOTENCY_KEY_REUSED.
• Неуспешные запросы (4xx и 5xx) не сохраняются: исправьте причину и повторите запрос с тем же ключом.
• Два одновременных запроса с одним ключом тоже безопасны: второй дождётся первого и получит его сохранённый ответ.
• Без заголовка повторный запрос — это новое изменение.

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" }

На практике

1. Создавайте ключ один раз на логическую операцию (например, на выплату приза за турнир) — до первой попытки.
2. Сохраняйте его вместе с операцией в своей базе, если повтор может случиться после перезапуска.
3. При тайм-ауте, сетевой ошибке, 429, 500 или 503 отправьте ровно тот же запрос с тем же ключом.
4. Для следующей, другой операции используйте новый ключ.