속도 제한 및 멱등성

멱등성

POST에 Idempotency-Key 헤더를 보내면 안전하게 재시도할 수 있습니다. 작업마다 새롭고 고유한 값 (UUID 또는 onboarding-8841 같은 자체 시스템의 ID)을 사용하세요. 값은 출력 가능한 ASCII 문자 1~255자입니다.

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 헤더 매개변수로 표시되어 있으며, 템플릿 생성, 파일 업로드, 게시, 봉투 생성과 무효화, 링크 재전송, 서명 세션 발급, 서명 링크 및 웹훅 엔드포인트 생성, 이벤트 재전송 등이 해당합니다.

자체 ID 기반 중복 제거

멱등성 키는 한 요청의 재시도를 보호합니다. 비즈니스 객체가 단 한 번만 발송되도록 하려면 자체 ID와 dedupeOn도 함께 보내세요.

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

그 externalId를 가진 봉투가 (같은 모드에) 이미 있으면 POST /v1/envelopes는 새로 만들지 않고 기존 봉투를 200 및 x-deduplicated: true와 함께 반환합니다. 이는 키, 날짜, 동시 요청에 관계없이 적용됩니다.

속도 제한

인증된 API(API 키)에는 현재 고정된 요청 속도 제한이 없으며, 발송량은 플랜에 따라 제한됩니다. 제한은 악용 가능성이 있는 곳에 적용됩니다.

대상	제한
`POST /v1/public/verify`	IP당 분당 60회 요청
`GET /v1/public/anchors…`, `/.well-known/bona-fide/*`	IP당 분당 240회 요청
`GET /v1/sso/discover`	IP당 분당 30회 조회
서명자 일회용 코드	세션당 15분에 코드 5개, 코드당 시도 5회
수신자 재전송	수신자당 1분에 한 번
상시 링크	링크별: `perEmailPerDay`(기본값 3), `perIpPerHour`(기본값 20), 선택적 `dailyCap`
대시보드 비밀번호 로그인	IP당 분당 10회, 이메일 주소당 15분에 10회
비밀번호를 사용한 대시보드 가입	IP당 분당 5회, 이메일 주소당 시간당 5회
비밀번호 재설정 이메일	IP당 15분에 5회, 이메일 주소당 시간당 3회
대시보드 로그인 코드	IP당 분당 3회

제한이 있는 공개 엔드포인트는 RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset(초) 헤더를 보냅니다. 한도를 넘으면 API는 rate-limited problem과 함께 429를 반환하며, 보통 초 단위의 Retry-After 헤더가 포함됩니다.