x-api-key이고, API 키가 전송되지 않은 경우에는 클라이언트 IP입니다. 각 범위는 60초 슬라이딩 윈도우를 사용하는 독립된 카운터를 유지합니다.
식별자 및 예외
미들웨어는 다음 순서로 속도 제한 식별자를 선택합니다.x-api-key헤더 → 키 범위 카운터.X-Forwarded-For의 첫 번째 홉 → IP 범위 카운터.REMOTE_ADDR→ IP 범위 카운터.
- 내부
DIDIT_WEBAPP_API_KEY(Didit 콘솔에서만 사용). IsValidSession권한으로 보호되는 엔드포인트(임베디드 및 SDK 세션 트래픽).GET /system/healthcheck(이 스택보다 먼저HealthMiddleware가 처리).- 제공업체 webhook: Stripe, AML 스크리닝, 얼굴 인증 콜백, KYC 목록 변경.
전역 제한
인증된 모든 요청은 HTTP 메서드별로 범용 범위에도 포함되므로, 새로 추가되는 라우트도 합리적인 기본값을 상속합니다.
거래 생성과 이벤트 수집은
generic-write 대신 ingest-write에 포함되어 계산됩니다. 따라서 대량 수집 연동은 다른 쓰기 작업의 한도를 소모하지 않고 API 키당 분당 600개의 요청을 사용할 수 있습니다.
엔드포인트별 제한(다음 섹션)은 전역 제한에 추가로 적용됩니다. 가장 먼저 카운터를 초과한 범위가 429를 반환합니다.
엔드포인트별 제한
미들웨어는 영향이 가장 큰 라우트에 대해 더 엄격한 범위를 정의합니다.GET /v3/session/<id>/decision/은 SessionV3RetrieveView가 처리하며 session-decision 범위에 포함되지 않습니다. 이 엔드포인트는 generic-get의 분당 600회 상한만 적용받습니다. 분당 100회의 결정 조회 제한은 v1 및 v2 결정 경로에만 적용됩니다.429 응답 형식
어떤 범위든 제한을 초과하면 다음 본문과 헤더가 포함된 HTTP429 응답을 받게 됩니다.
X-RateLimit-* 헤더는 429 응답에만 포함됩니다. 현재 성공 응답에는 이 헤더가 포함되지 않습니다. 다음 시도 전 대기 시간으로 Retry-After 값(또는 X-RateLimit-Reset - now)을 사용하십시오.
클라이언트 가이드
Retry-After를 백오프의 최소 대기 시간으로 사용하십시오. 여기에 지수 백오프와 지터를 더하십시오(5s → 10s → 20s → 40s ± random). 그러면 같은 시점에429를 받은 두 클라이언트가 동시에 재시도하며 동기화되는 일을 막을 수 있습니다.- 일정 횟수 이후에는 재시도를 중단하십시오. 소규모 상한(예: 5회)에 도달하면 재시도를 멈추고 오류를 호출한 쪽에 전달한 뒤 팀에 알림을 보내십시오. 지속적인 429 오류는 일시적인 급증이 아니라 보통 제어되지 않는 반복 루프를 의미합니다.
- 작업마다 식별자 하나를 사용하십시오. 여러 백엔드에서
x-api-key를 공유하면 모두 같은 카운터에 합산되어, 요청이 많은 하나의 워크로드가 나머지를 굶길 수 있습니다. 환경, 브랜드 또는 고객별로 별도의 애플리케이션(따라서 별도의api_key)을 발급하십시오. 프로그래밍 방식 등록을 참고하십시오. - 결정 조회 결과를 캐시하십시오.
/decision/엔드포인트는 촘촘한 폴링 루프를 위해 설계되지 않았습니다. 실시간 업데이트가 필요하면 Webhook을 사용하고,GET /v3/session/<id>/decision/은 백필이나 감사 목적으로만 호출하십시오. - PDF는 오프라인으로 생성하십시오. PDF 렌더링은 CPU 바운드 작업입니다(분당 50회 상한). 페이지를 조회할 때마다가 아니라, 세션이 최종 상태에 도달한 후 큐에서 실행하십시오.
429 응답을 처리하는 샘플 클라이언트
더 많은 여유가 필요하신가요?
분당 600개 세션으로 충분하지 않다면(예: 마케팅 출시나 백필 작업), support@didit.me로 이메일을 보내 주십시오. 이메일에는application UUID와 예상 지속 속도 및 순간 속도를 적어 주십시오. 한도 재정의는 애플리케이션 단위로 설정됩니다.