Повторы запросов

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

Зачем

Сеть ненадёжна. Вы отправили запрос на создание контакта, ответ не дошёл — и вы не знаете, создался контакт или нет. Повторить страшно: можно получить два одинаковых контакта.

Для этого есть заголовок Idempotency-Key.

Как пользоваться

Придумайте уникальную строку на каждую логическую операцию (подойдёт UUID) и приложите её к запросу:

curl -X POST "https://api.tygy.ru/v1/contacts" \
  -H "Authorization: Bearer $TYGY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 2f1c8e40-1f2a-4b6d-9d3e-7a5c1b2d3e4f" \
  -d '{"name": "Иван Петров", "email": "ivan@example.com"}'

Если ответ не дошёл — повторите запрос с тем же ключом и тем же телом. Мы вернём сохранённый ответ первого запроса, а не выполним операцию заново. В повторном ответе будет заголовок:

Idempotency-Replayed: true

Правила

• Ключ работает для всех изменяющих методов: POST, PATCH, PUT, DELETE.
• Ключ живёт 24 часа, потом забывается.
• Ключ действует внутри вашего проекта.
• Длина — не больше 255 символов.
• Тот же ключ с другим телом — ошибка. Ответ 422 с кодом idempotency_mismatch. Это защита от случайного повторного использования ключа: иначе вы бы молча получили ответ на совсем другую операцию.
• Неудачные запросы не запоминаются. Если первый запрос упал с ошибкой 500, повтор с тем же ключом выполнится честно заново — так и задумано.

Когда можно не пользоваться

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