본문으로 건너뛰기

OpenAPI 요청 제한

카카오클라우드 OpenAPI는 모든 사용자에게 안정적이고 신뢰할 수 있는 API 서비스를 제공하기 위해 요청 제한(Rate Limit) 정책을 운용합니다. 특정 클라이언트나 시스템에서 과도한 요청이 발생할 경우 시스템 자원 고갈을 방지하고, 서비스 전반의 고가용성을 유지하기 위해 요청을 제한할 수 있습니다.

이 문서에서는 기본 할당량, 제한 기준, 할당량 초과 시 응답, 클라이언트 오류 처리 권장 방식을 설명합니다.

기본 제공 할당량​

카카오클라우드 OpenAPI는 별도 추가 설정 없이 다음 기본 정책을 통합 적용합니다. 제한은 식별 기준별로 독립적으로 산정됩니다.

  • 다중 레이어 제한: 요청은 DOMAIN, PROJECT, IP, USER 기준을 모두 만족해야 합니다. 하나의 기준이라도 임계값을 초과하면 요청이 차단됩니다.
  • 독립 카운팅: 예를 들어 사용자 A의 요청량이 증가하더라도 같은 프로젝트의 사용자 B 요청 카운트에는 영향을 주지 않습니다.
제한 기준초당 제한분당 제한조정 가능 여부
도메인(DOMAIN)1,000건    5,000건    가능
프로젝트(PROJECT)100건3,000건가능
IP 주소(IP)30건600건가능
사용자(USER)10건300건가능
정보
  • 안내된 할당량은 시스템 안정성을 위해 모든 사용자에게 공통적으로 적용됩니다.
  • 할당량 조정이 필요한 경우 헬프데스크를 통해 문의해 주세요.

초과 시 응답 및 오류 처리​

정해진 할당량을 초과하여 요청이 차단되는 경우 API 서버는 HTTP 응답 코드 429, 상태 메시지 Too Many Requests, 오류 메시지를 반환합니다.

429 응답을 수신한 클라이언트는 다음 모범 사례를 적용하는 것을 권장합니다.

  • 지수 백오프(Exponential Backoff) 재시도: 즉시 연속 요청을 보내지 않고 대기 시간을 두 배씩 늘려가며 재시도합니다.
  • 지터(Jitter) 추가: 재시도 대기 시간에 무작위 지연 값을 추가하여 동시에 다수의 클라이언트가 요청을 집중시키는 현상(Thundering Herd Problem)을 방지합니다.
  • 요청 분산: 배치 작업이나 대량 호출 시 초당/분당 제한 내로 유지되도록 요청 속도를 조절합니다.