Доступно

Idempotency-Key: безопасные повторы без двойного списания

Как создавать и повторно использовать Idempotency-Key, обрабатывать таймауты, replay и конфликт тела запроса.

API Токенмоста работает

Базовый адрес — https://tokenmost.ru/v1. Создайте ключ в личном кабинете, выберите модель в каталоге и отправьте первый запрос. Методы, которые ещё не доступны, отмечены отдельно.

Как это устроено

Idempotency-Key связывает повторные попытки с одной логической платной операцией. Первый запрос резервирует средства и сохраняет итог; повтор с тем же ключом и тем же телом возвращает прежний результат без второго вызова модели.

Что потребуется

Стабильное сериализованное тело запроса для повторной отправки.
Хранилище ключа операции до получения однозначного результата.
Разделение нового пользовательского действия и сетевого повтора.

Порядок работы

Создайте UUID или другой случайный ключ длиной 8–128 символов один раз на логическую операцию.
Сохраните ключ рядом с локальным статусом запроса до отправки.
При таймауте проверьте историю и повторите неизменное тело с тем же ключом.
После подтверждённого успеха сохраните receipt и не отправляйте операцию снова.
Для нового пользовательского действия создайте новый Idempotency-Key.

Готовая конфигурация

Создать ключ в JavaScript

const idempotencyKey = crypto.randomUUID();

await fetch("https://tokenmost.ru/v1/responses", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.TOKENMOST_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": idempotencyKey,
  },
  body: JSON.stringify(requestBody),
});

Пример запроса

Укажите TOKENMOST_BASE_URL=https://tokenmost.ru/v1, ключ проекта и точный ID модели из каталога. Пример отправляет запрос в публичный API и может списать средства с баланса по тарифу модели.

curl "$TOKENMOST_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $TOKENMOST_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: example-request-0001" \
  -d '{
    "model": "MODEL_ID_FROM_CATALOG",
    "messages": [{"role": "user", "content": "Объясни API в двух предложениях."}],
    "max_tokens": 128
  }'

Что учесть

Новый Idempotency-Key после неопределённого сетевого результата означает новую платную операцию. Сначала выясните состояние исходного запроса.

Replay

Повтор подтверждённого запроса с тем же ключом и идентичным телом возвращает сохранённый публичный результат. Поставщик повторно не вызывается и второе списание не создаётся.

Неопределённый исход

Если соединение оборвалось после отправки поставщику, сервис может сохранить резерв до сверки. Не создавайте новый ключ: это не доказывает, что первая генерация не состоялась.

Каноническое тело

Тот же ключ нельзя использовать для изменённой модели, промпта или параметров. Конфликт тела возвращает 409 вместо запуска новой операции.

Ошибки и диагностика

HTTP 409

Ключ уже связан с другим телом. Для нового действия создайте новый ключ; для повтора восстановите исходное тело.

Таймаут без ответа

Сохраните ключ, проверьте историю и повторяйте только с тем же ключом.

Повтор снова списал деньги

Проверьте, не сгенерировал ли клиент новый ключ автоматически и не изменил ли тело.

Ключ слишком короткий

Используйте UUID или другую случайную строку длиной от 8 до 128 символов.

Источники и связанные инструкции

Читайте дальше

← Все инструкции