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

Для операций, которые могут списывать кредиты, передавайте уникальный ключ:

Idempotency-Key: order-7f36-image-cover-v1

Один логический запрос должен всегда использовать один ключ. Новый запрос — новый ключ. Подходящие значения: UUID или устойчивый идентификатор операции приложения.

Повторять можно

• сетевой разрыв до получения ответа;
• 408, 429 и временные 5xx с backoff;
• неопределённый результат после таймаута — с тем же ключом.

Не повторять автоматически

• 400 — исправьте payload;
• 401/403 — исправьте доступ;
• ошибка недостаточного баланса;
• повтор с изменённым телом под тем же ключом.

Храните ключ рядом со статусом бизнес-операции, чтобы повтор после перезапуска процесса не создал дубликат.