Идемпотентность и безопасные повторы

Сети дают сбои. Запрос может дойти до нас, а ответ — не дойти до вас. Идемпотентность делает повтор безопасным: тот же запрос снова возвращает результат первого и ничего не делает дважды.

Ключ

Передавайте Idempotency-Key — от 1 до 200 символов, UUID подойдёт — в каждой команде, которая создаёт или меняет деньги:

Команда	Ключ	Второй ключ
POST /v1/payments	обязателен	merchant_order_id
POST /v1/payments/{id}/cancel	обязателен	—
POST /v1/payments/{id}/amount-correction	обязателен	—
POST /v1/payments/{id}/refunds	обязателен	—
POST /v1/payouts	обязателен	merchant_payout_id
POST /v1/payouts/{id}/cancel	обязателен	—

Чтению и настройкам вебхуков ключ не нужен.

• Тот же ключ, то же тело → снова первый ответ: тот же объект, Idempotent-Replayed: true для платежей и выплат.
• Тот же ключ, другое тело → 409 idempotency_conflict. Для нового запроса берите новый ключ.
• Тот же merchant_order_id или merchant_payout_id под новым ключом, то же тело → объект, созданный первым, как повтор. С другим телом → 409 idempotency_conflict. Двойной клик, который отправил два ключа, всё равно создаёт один платёж.

Повторы

Вы получили	Что делать
Таймаут или обрыв соединения	Повторите с тем же ключом и телом.
503 payment_unavailable, payout_unavailable	Результат неизвестен. Повторите с тем же ключом или прочитайте объект.
409 payment_busy	Подождите Retry-After (1 с) и повторите с тем же ключом.
429 rate_limited	Подождите Retry-After (1 с) и повторите с тем же ключом.
400, 404, 409 idempotency_conflict, 422	Не повторяйте: исправьте запрос.

Каждый повтор — новая подпись: новые nonce и метка времени, тот же Idempotency-Key. Увеличивайте паузу — 1, 2, 4, 8 секунд — и остановитесь после нескольких попыток; затем сверьтесь чтением.

Создавайте ключ, когда решаете сделать запрос, — в момент оформления заказа — и храните его вместе с заказом, чтобы повтор после перезапуска вашего процесса использовал тот же ключ.