Что такое safe и idempotent методы и Idempotency-Key?
На этой странице
Safe method не должен менять состояние сервера. Idempotent method можно повторить несколько раз, и итоговое состояние будет таким же, как после одного запроса. Для неидемпотентных операций (платежи, заказы) используют Idempotency-Key. Эти свойства важны для кеширования, retries и проектирования REST API.
Вопрос
Что значит safe и idempotent? Какие методы такими являются? Как защитить POST /payments от двойного выполнения?
Safe methods
Safe method предназначен для чтения.
GET /api/articles
HEAD /api/articles/1
OPTIONS /api/articles/1GET может писать технические логи или метрики, но не должен создавать заказ, списывать деньги или менять профиль пользователя.
Плохой пример:
GET /api/orders/create?productId=10Такой endpoint опасен: browser, crawler, prefetch или cache layer могут выполнить GET, не ожидая изменения данных. Кроме того, state-changing GET легко эксплуатировать через CSRF: достаточно <img src="..."> на чужой странице.
Idempotent methods
Idempotent значит: один и тот же запрос можно повторить, а результат в системе останется тем же.
PUT /api/users/1
{
"name": "Anna"
}Если отправить этот PUT пять раз, имя все равно будет Anna.
DELETE /users/1 тоже обычно idempotent по смыслу: после первого удаления пользователя уже нет, после повторного он все еще отсутствует. Но конкретный status code может отличаться: первый раз 204, второй раз 404 или тоже 204. Идемпотентность — про состояние сервера, а не про одинаковый ответ.
POST обычно не idempotent
POST /api/orders
{
"productId": 10,
"quantity": 1
}Если browser, mobile app или proxy повторит request (timeout, нестабильная сеть, двойной клик), можно создать два заказа.
Idempotency-Key
Для опасных POST операций клиент генерирует уникальный ключ и отправляет его в header:
POST /api/payments
Idempotency-Key: 5f7f8f6e-4d53-4c37-9f4f-1f9df5a1c101Server сохраняет результат первого request с таким ключом. Если такой же request повторится, server вернет сохраненный результат, а не создаст новую операцию. Если с тем же ключом пришло другое тело запроса, сервер обычно отвечает 409 или 422.
const idempotencyKey = crypto.randomUUID(); // один ключ на одну попытку оплаты
async function pay(amount: number) {
return fetch('/api/payments', {
method: 'POST',
headers: { 'Content-Type': 'application/json', 'Idempotency-Key': idempotencyKey },
body: JSON.stringify({ amount }),
});
}Где это важно:
- payments;
- order creation;
- booking;
- sending email/SMS;
- imports и file processing;
- webhook handlers (провайдер может прислать событие повторно).
Таблица
| Метод | Safe | Idempotent |
|---|---|---|
GET | да | да |
HEAD | да | да |
OPTIONS | да | да |
PUT | нет | да |
PATCH | нет | зависит от реализации |
DELETE | нет | обычно да |
POST | нет | обычно нет |
Frontend-угол
На frontend idempotency помогает пережить двойной клик, retry после timeout, нестабильную мобильную сеть и повторную отправку формы после refresh. Но кнопку все равно нужно блокировать на время submit: Idempotency-Key — защита backend-уровня, а не замена нормального UX.
Что важно помнить
- Автоматические retries (в fetch-обертках, TanStack Query, axios-retry) безопасны только для idempotent запросов.
PATCH { "count": count + 1 }с вычислением на клиенте идемпотентен, аPATCH { "increment": 1 }— нет.- Ключ генерируется на одну логическую операцию: новый клик «Оплатить» после успешной оплаты — новый ключ.
- Сервер хранит ключи ограниченное время (часто 24 часа) и должен атомарно обрабатывать одновременные запросы с одним ключом.
Мини-шпаргалка
- Safe - не меняет состояние.
- Idempotent - повтор не меняет итоговое состояние.
GETне должен выполнять действия.POSTможет создать дубликаты при retry.Idempotency-Keyнужен для платежей, заказов и других критичных операций.
Документация
MDN: Safe methods, MDN: Idempotent, IETF: Idempotency-Key header (draft).