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

Любой POST/PATCH с побочным эффектом в публичной аудитории принимает заголовок Idempotency-Key — и требует его, если вызов напрямую двигает деньги или кредиты (создание ссылки, генерация QR, любой платный вызов). Без заголовка на таком эндпоинте — 400 invalid_request.

Idempotency-Key: 8f1c6e2a-9b7d-4e3f-9a21-9c2b7a0f5e41

Берите новый UUID (или ULID) на каждое отдельное действие, и переиспользуйте то же значение только при повторе того же действия после таймаута, обрыва соединения или 5xx. Что вернётся при повторе — зависит от того, что вы отправили:

Вы отправили	Вы получили
Новый ключ	Действие выполняется
Тот же ключ, то же тело, действие уже завершилось	Прежний ответ без повторного списания (`Idempotent-Replayed: true`)
Тот же ключ, ещё выполняется	`409 idempotency_in_progress` + `Retry-After`
Тот же ключ, другое тело	`422 idempotency_key_reused` — возьмите новый ключ
Тот же ключ, прошлая попытка упала до начала работы (авторизация, валидация, нехватка кредитов, лимит)	Действие выполняется — можно повторять, устранив причину

Ключи привязаны к аккаунту, хранятся 24 часа, а в повторяемом ответе никогда не будет одноразовых секретов (только что выпущенный API-ключ, секрет подписи вебхука) — они возвращаются скрытыми по дизайну; если секрет потерян, выпустите новый вместо повтора.

В MCP это параметр idempotency_key — обязателен в каждом платном write-инструменте, необязателен в бесплатных. Композитные инструменты (один вызов — несколько шагов) используют производные ключи внутри; вы передаёте только один.

Далее: Quickstart REST · Кредиты