Ограничения частоты и идемпотентность

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

Передайте заголовок Idempotency-Key в запросе POST, чтобы его можно было безопасно повторить. Используйте новое уникальное значение для каждой операции (UUID или идентификатор из вашей системы, например onboarding-8841): от 1 до 255 печатных символов ASCII.

curl https://api.bonafidesign.com/v1/envelopes \
  -H "Authorization: Bearer $BONA_FIDE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c2f0e-1d0b-4c2a-9a59-3f1f1c7d2b11" \
  -d @envelope.json

Первый запрос с ключом выполняется как обычно, а его ответ хранится 24 часа.
Повтор с тем же ключом и тем же запросом (метод, путь, параметры запроса и тело) получает сохранённый ответ повторно, с заголовком Idempotent-Replayed: true.
Тот же ключ с другим запросом даёт 422 idempotency-key-reused.
Повтор, пока первый запрос ещё выполняется, даёт 409 idempotency-in-progress; повторите чуть позже.
Ответы 5xx не сохраняются, поэтому повтор после ошибки сервера выполняется заново.

Ключи привязаны к вызывающей стороне: организации и ключу API (или пользователю панели управления), которые их отправили. Операции, принимающие ключ, отмечены в справочнике API параметром заголовка Idempotency-Key; среди них создание шаблонов, загрузка файлов, публикация, создание и аннулирование конвертов, повторная отправка ссылок, создание сессий подписания, создание ссылок для подписания и конечных точек вебхуков, а также повторная доставка событий.

Дедупликация по собственному идентификатору

Ключи идемпотентности защищают повторы одного запроса. Чтобы бизнес-объект гарантированно отправлялся только один раз, передавайте также собственный идентификатор и dedupeOn:

{ "template": "tpl_…", "externalId": "user_8841", "dedupeOn": "external_id", "…": "…" }

Если конверт с таким externalId уже существует (в том же режиме), POST /v1/envelopes возвращает его с 200 и x-deduplicated: true вместо создания нового. Это действует для разных ключей, разных дней и параллельных запросов.

Ограничения частоты

У аутентифицированного API (ключи API) сейчас нет фиксированного ограничения частоты запросов; объём отправки ограничен вашим тарифом. Ограничения действуют там, где возможны злоупотребления:

Где	Ограничение
`POST /v1/public/verify`	60 запросов в минуту с одного IP
`GET /v1/public/anchors…`, `/.well-known/bona-fide/*`	240 запросов в минуту с одного IP
`GET /v1/sso/discover`	30 запросов в минуту с одного IP
Одноразовые коды для подписантов	5 кодов за 15 минут на сессию; 5 попыток на код
Повторная отправка получателю	Раз в минуту на получателя
Постоянные ссылки	На ссылку: `perEmailPerDay` (по умолчанию 3), `perIpPerHour` (по умолчанию 20), необязательно `dailyCap`
Вход в панель управления по паролю	10 в минуту с одного IP; 10 за 15 минут на адрес электронной почты
Регистрация в панели управления с паролем	5 в минуту с одного IP; 5 в час на адрес электронной почты
Письма для сброса пароля	5 за 15 минут с одного IP; 3 в час на адрес электронной почты
Коды входа в панель управления	3 в минуту с одного IP

Публичные конечные точки с ограничениями отправляют заголовки RateLimit-Limit, RateLimit-Remaining и RateLimit-Reset (в секундах). При превышении лимита API отвечает 429 с проблемой rate-limited, обычно с заголовком Retry-After в секундах.