API 요청 수 제한(Rate Limits)

기본 정책

API 요청 수는 API Key 단위로 제한됩니다. 조회·발급·회수 등 모든 메서드의 요청이 합산되어 계산됩니다.

기준	제한
API Key	분당 1,000회

요청 수 제한은 모든 API Key에 동일하게 적용되며, 계약이나 서비스 등급에 따른 차등은 없습니다. 허용 요청 수는 서비스 정책에 따라 사전 공지 후 변경될 수 있습니다.

대량 처리는 배치 API를 사용하세요

단건 발급(POST /api/v1/ext/badges)을 반복 호출해 대량 발급하면 분당 한도에 걸려 429 가 발생합니다. 여러 건은 배치 발급(POST /api/v1/ext/badges/batch, 요청당 최대 1,000건)으로 한 번에 접수하세요. 이때 실제 상한은 요청 수 제한이 아니라 발급 한도(Quota)입니다.

제한 초과 시 응답

분당 허용치를 초과하면 429 Too Many Requests 로 응답하며, 응답 헤더에 재시도까지 남은 시간이 담깁니다.

항목	값
HTTP 상태	429 Too Many Requests
Retry-After 헤더	다시 요청 가능해지기까지 남은 시간(초)

HTTP/1.1 429 Too Many Requests
Retry-After: 42

{ "code": "4011", "message": "요청 횟수를 초과했습니다.", "data": null }

초과 시 대응

429 를 받으면 즉시 재시도하지 말고, Retry-After 헤더의 초만큼 대기한 뒤 다시 요청하세요. 잔여 한도를 넘기지 않도록 클라이언트에서 요청 속도를 조절하는 것을 권장합니다.

발급 한도 (Quota)

배지 발급은 계약 등급별 발급 한도(quota) 내에서만 가능합니다. 한도를 초과한 발급 요청은 422 Unprocessable Entity 로 거부됩니다. 발급 한도는 요청 수 제한(Rate Limit)과 별개로 적용됩니다.

페이지네이션

목록 조회는 page(기본 1)와 rows_per_page(기본 20, 최대 100)로 페이지네이션합니다. 응답 항목에는 결과 내 순번 rnum 과 전체 결과 수 total_count 가 포함됩니다.

파라미터	기본값	설명
page	1	조회할 페이지 번호
rows_per_page	20	페이지당 항목 수 (최대 100)

음수이거나 rows_per_page 상한을 초과하는 값은 400 으로 응답합니다.