메인 콘텐츠로 건너뛰기
Didit는 API를 안정적으로 유지하면서도 정상적인 트래픽 급증은 허용하도록 여러 계층의 속도 제한을 적용합니다. 제한은 식별자별로 적용되며, 식별자는 x-api-key이고, API 키가 전송되지 않은 경우에는 클라이언트 IP입니다. 각 범위는 60초 슬라이딩 윈도우를 사용하는 독립된 카운터를 유지합니다.

식별자 및 예외

미들웨어는 다음 순서로 속도 제한 식별자를 선택합니다.
  1. x-api-key 헤더 → 키 범위 카운터.
  2. X-Forwarded-For의 첫 번째 홉 → IP 범위 카운터.
  3. 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 결정 경로에만 적용됩니다.
코드베이스에는 FREE_SESSION_RATE_LIMIT = 10과 PAID_SESSION_RATE_LIMIT = 600 상수도 정의되어 있습니다. 이 상수들은 현재 POST /v3/session/에 적용되지 않습니다. 해당 엔드포인트는 모든 애플리케이션에 대해 단일 session-v2-create 제한인 분당 600회를 사용합니다. 이 제한이 문서에서 실제 동작하는 것으로 확인되기 전까지는 워크플로별 무료 요금제 제한을 전제로 용량을 계획하지 마십시오.

429 응답 형식

어떤 범위든 제한을 초과하면 다음 본문과 헤더가 포함된 HTTP 429 응답을 받게 됩니다.
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와 예상 지속 속도 및 순간 속도를 적어 주십시오. 한도 재정의는 애플리케이션 단위로 설정됩니다.
마지막 수정일 2026년 11월 7일