Идемпотентность

Если связь оборвалась до ответа, интеграция не знает, выполнился ли запрос. Повторять запрос на заказ или продление вслепую опасно: он может выполниться второй раз. Заголовок Idempotency-Key снимает эту неопределённость: запрос с тем же ключом выполняется не больше одного раза.

Когда передаватьСкопировать ссылку на раздел

Как это работаетСкопировать ссылку на раздел

Ключ идемпотентности — строка от 8 до 128 знаков из латинских букв, цифр и символов _ : . -. Удобно использовать UUID, созданный для каждой операции.

curl https://api.skystream.su/app/v1/orders/views \  -X POST \  -H "Authorization: Bearer $API_KEY" \  -H "Idempotency-Key: 7c0a5f4e-2b1d-4c9e-9a51-3f6d8e2b1c40" \  -H "Content-Type: application/json" \  -d '{    "channel": "example_channel",    "views": 1000  }'

1. Первый запрос с ключом выполняется, и его ответ сохраняется вместе с ключом.
2. Повтор с тем же ключом и тем же запросом не выполняется заново: API возвращает сохранённый ответ с тем же кодом и заголовком Idempotent-Replayed: true.
3. Ключ хранится 24 часа. После этого запрос с ним считается новым.

Сохранённый ответ приходит с тем же кодом и телом, что и первый, и с заголовком Idempotent-Replayed: true:

HTTP/1.1 201 Created
Content-Type: application/json
Idempotent-Replayed: true

В теле — тот же заказ с тем же id и той же суммой. Второго списания нет.

Ключи идемпотентности общие для всех ключей API аккаунта: повтор, отправленный другим ключом того же аккаунта, тоже вернёт сохранённый ответ.

ПравилаСкопировать ссылку на раздел

• Один ключ — один запрос. Запрос с тем же ключом, но с другим адресом, строкой запроса или телом отклоняется с ошибкой 422 idempotency_key_reused. Для новой операции создавайте новый ключ.
• Пока первый запрос выполняется, повтор с тем же ключом получает 409 idempotency_key_in_progress. Дождитесь ответа и повторите запрос.
• Ошибка в запросе ключ освобождает. Если запрос отклонён — нехватка денег, неверное поле, превышен суточный потолок, — ключ не сохраняется: исправьте причину и повторите запрос с тем же ключом.
• Сбой посреди запроса ключ не освобождает. Если запрос завершился ошибкой 500 internal_error во время выполнения, этот ответ сохраняется под ключом: повтор с тем же ключом получит его же и действие второй раз не выполнит. Прежде чем повторять операцию с новым ключом, проверьте, выполнилась ли она: например, найдите заказ в GET /orders.

Рекомендуемый порядокСкопировать ссылку на раздел

1. Создайте ключ идемпотентности до первой попытки и сохраните его вместе с операцией.
2. При обрыве связи, тайм-ауте или ответе 5xx, кроме 500 internal_error, повторите запрос с тем же ключом.
3. Получив ответ, сохраните результат и больше этот ключ не используйте.

Пример клиента, который так повторяет запросы, — в разделе Ошибки.