Docs

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

Последнее обновление: 2026-10-033 мин чтения

Сеть иногда обрывает запрос, и неизвестно, дошел ли он. Чтобы повторить POST и не выполнить (и не оплатить) работу дважды, передайте заголовок Idempotency-Key - уникальное значение на каждую логическую операцию. Хорошо подходит UUID.

curl -X POST https://developers.grem.capital/api/v1/valuation/express \
  -H "Authorization: Bearer gsk_live_xxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 3f1c8a90-1e2b-4c77-9a10-2b6d0f9e4a11" \
  -d '{"propertyCategory":"apartment","addressText":"Torstraße 12, Berlin","totalArea":64}'

Как это работает

  • Первый запрос с ключом выполняется обычно, его успешный ответ запоминается.
  • Повтор с тем же ключом возвращает сохраненный ответ: инструмент не запускается второй раз и не списывается второй раз.
  • Пока первый запрос еще выполняется, второй запрос с тем же ключом получает 409 с title: idempotency_conflict. Дождитесь и повторите с тем же ключом.
  • Если первый запрос завершился ошибкой, ключ освобождается - повтор с ним выполнится заново. Запрос, который не дошел до сервиса (отказ соединения), тоже освобождает ключ.
  • После таймаута (502 provider_error) инструмента, создания объекта или создания лида ключ остается занятым 15 минут, чтобы повтор не выполнил работу второй раз. Прежде чем повторять, проверьте результат: для инструментов - GET /works, для создания - GET /objects и GET /leads. Результаты улучшения фото, сайта и черновика в GET /works не хранятся - проверяйте их в кабинете или среди своих объектов. Повтор после 15 минут выполнит работу (и спишет ее) еще раз.
  • Исключение - экспресс-оценка: после таймаута ключ освобождается - повторите ее с тем же ключом сразу, готовая оценка вернется бесплатно: ни оценка, ни вызов API второй раз не списываются.
  • Ключ помнится 24 часа и принадлежит вашему API-ключу и операции - методу и фактическому пути: одинаковые значения разных API-ключей, тот же ключ на другом инструменте, а также POST /objects/property и POST /objects/rental - разные запросы.

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

Где действует

Запрос
POST /valuation/express и все инструменты (POST /valuation/report, POST /content/generate, POST /flyer/create и т. д.)да
POST /objects/{kind} - создание объектада
POST /leads - создание лидада
POST /match/leads/{id}/events - событие Swipe Matchда; ключ должен соответствовать ^[A-Za-z0-9_.:-]{8,128}$, иначе он игнорируется
POST /uploads, POST /chat/messages, POST /valuation/review/jobs/{id}/confirmнет (в чате для этого есть clientMessageId)

В SDK ключ передается последним аргументом метода.

Связанные статьи

Эта статья была полезной?