EN
Разделы документации

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

Как повторить запрос после таймаута или обрыва связи и не продать один билет дважды.

Связь рвётся. Запрос мог дойти и выполниться, а ответ потеряться. Чтобы повтор не создал второй заказ, передайте заголовок Idempotency-Key:

http

Idempotency-Key: order-1042

Правила

  • Ключ учитывается в запросах POST и DELETE. В GET, PATCH и PUT он не нужен.
  • Ключ — любая строка до 255 символов. Удобно брать номер заказа на вашей стороне.
  • Ключ живёт 24 часа с первого запроса. Ключи разных организаций и режимов не пересекаются: тестовый запрос никогда не получит ответ боевого.
  • Повтор с тем же ключом, методом, путём и телом получает сохранённый ответ: тот же статус и то же тело байт в байт, с заголовком Idempotent-Replayed: true.
  • Тело сравнивается без пробелов между элементами JSON, но порядок полей и запись чисел важны. {"a":1,"b":2} и {"b":2,"a":1} — разные запросы.
  • Тот же ключ с другим телом или путём получит 409 idempotency_conflict.

Где ключ обязателен

POST /v1/events/{id}/issue без ключа отвечает 400 invalid_request. Для заказа, резерва и события ключ не обязателен, но без него повтор создаст новый объект. Передавайте ключ во всех запросах, которые что-то создают.

Что вернёт повтор

Первый запросПовтор с тем же ключом
ответил 2xxтот же ответ
ответил 4xx, например 409 sold_outтот же отказ, даже если билеты потом вернулись в продажу. Для новой попытки нужен новый ключ
ещё выполняется409 idempotency_conflict: повторите через несколько секунд
упал с 5xx до того, как мы начали создавать объектвыполняется заново
упал с 5xx во время создания заказа, события или выдачи409 idempotency_conflict с details.idempotency_state: "unknown", см. ниже
подтверждение резерва ответило 202выполняется заново и показывает свежее состояние заказа

Отмена резерва, отмена билета, перевыпуск и публикация безопасны сами по себе: их повтор после сбоя на нашей стороне просто выполнится ещё раз.

Неизвестный результат

Если создание заказа оборвалось на нашей стороне, заказ мог успеть создаться. Повтор с тем же ключом ответит так:

Ответ 409

{
  "error": {
    "code": "idempotency_conflict",
    "message": "Результат запроса с этим Idempotency-Key неизвестен: он мог выполниться. Проверьте состояние, прежде чем повторять запрос с новым ключом",
    "details": {
      "idempotency_state": "unknown",
      "order_id": "0193e0c5-1f20-7c3e-b6a1-9d4e2f7a8b10"
    }
  }
}

Прочитайте заказ из details.order_id через GET /v1/orders/{id}. Заказ в статусе paid или issued уже продан, второй не нужен. Новый заказ с новым ключом создавайте, только если заказа нет или он cancelled.

Где ключ не действует

  • POST /v1/devices/invites: каждый вызов создаёт новое приглашение.
  • POST /v1/events/{id}/seats: загрузка мест заменяет все места черновика, повтор того же файла даёт тот же результат.
  • POST /v1/events/{id}/imports: тот же список гостей для того же события возвращает прежнюю загрузку с repeated_file: true, второй раз билеты не выдаются.
  • PUT /v1/events/{id}/cover: повтор ставит ту же обложку.