메인 콘텐츠로 건너뛰기
API 키에는 분당 요청 한도를 정할 수 있습니다. 한도는 키를 발급할 때 ‘분당 요청 한도’를 적은 키에만 걸리고, 비워 두면 그 키는 한도 없이 씁니다. 한도를 넘은 요청은 429 rate_limit_exceeded와 Retry-After 헤더를 받습니다.

한도를 정해 키 발급하기

키 발급은 콘솔에 로그인한 상태에서만 됩니다. 발급 절차 전체와 키 보관 방법은 API 키 발급과 첫 호출을 보세요.
1

발급 창을 연다

콘솔 왼쪽 메뉴에서 ‘API 키와 통보’ 화면을 열고 ‘서버 연동 키’ 구역의 ‘API 키 발급’을 누릅니다.
2

분당 요청 한도를 적는다

‘분당 요청 한도’에 1 이상 2,147,483,647 이하의 정수를 적습니다. 비우면 무제한입니다.
3

발급한 키의 한도를 확인한다

키 목록의 ‘분당 한도’ 열에 정한 값이 보입니다. 한도를 정하지 않은 키는 ‘무제한’으로 표시됩니다.
API 참조의 키 발급 요청(POST /v1/api-keys, 콘솔 로그인 전용)에서는 같은 값을 rate_limit_per_minute으로 보냅니다. 양수만 받고, 빼거나 null로 보내면 무제한입니다.

한도를 세는 방식

  • 키마다 따로 셉니다. 키 두 개를 쓰면 한도도 두 개입니다. 같은 키를 여러 연동 서버가 나눠 쓰면 한도를 함께 씁니다.
  • 1분 단위로 끊어 세지 않습니다. 처음에는 한도만큼 연달아 보낼 수 있고, 다 쓴 뒤에는 1분에 한도만큼의 속도로 조금씩 다시 채워집니다. 예를 들어 한도가 60이면 한 번에 60건까지 보낼 수 있고, 그 뒤에는 1초에 1건꼴로 보낼 수 있습니다.
  • 키 확인을 통과한 요청은 결과와 관계없이 셉니다. 400, 403, 404로 끝난 요청도 한 번입니다. 키가 없거나 틀려서 401을 받은 요청은 세지 않습니다.
  • 이벤트 배치는 한 요청을 한 번으로 셉니다. POST /v1/event-batches에 이벤트 100건을 담아도 한 번입니다.
  • 콘솔 로그인으로 보낸 요청은 세지 않습니다. 한도는 API 키에만 걸립니다.
한도는 MeterEngine 서버마다 따로 셉니다. 요청을 여러 서버가 나눠 처리하면 실제 허용량이 정한 값보다 많을 수 있고, 서버가 다시 시작되면 처음부터 다시 셉니다. 한도는 상한을 보장하는 장치가 아니라 연동 쪽 폭주를 막는 장치로 쓰세요.

429 응답

한도를 넘으면 아래처럼 응답합니다. Retry-After는 다시 보내기 전에 기다릴 초이며 1 이상의 정수입니다.
429를 받은 요청은 처리되지 않은 것입니다. Retry-After만큼 기다렸다가 같은 요청을 그대로 다시 보내면 됩니다. 아래는 이벤트 배치를 보내다 429를 받으면 기다렸다가 다시 보내는 예시입니다.
이벤트가 많으면 단건 요청 대신 배치로 묶어 보내세요. 한 요청에 100건까지 담을 수 있고 한도는 한 번만 씁니다. 배치 응답 읽는 법은 사용량 이벤트 보내기를 보세요.
429를 받는 동안 보내지 못한 이벤트를 쌓아 두었다가 다시 보내는 방법은 재전송 설계를 보세요.

한도 바꾸기

발급한 키의 한도는 바꿀 수 없습니다. ‘API 키와 통보’ 화면의 ‘키 권한 변경’은 권한만 바꿉니다. 한도를 바꾸려면 새 한도로 키를 새로 발급하면서 ‘교체할 기존 키’에 지금 쓰는 키를 고르세요. 기존 키는 교체 유예 시간이 지나면 만료되고, 새 키는 처음부터 새 한도로 셉니다. 교체 절차는 키 교체, 권한 변경, 폐기를 보세요.

로그인과 가입 신청의 한도

콘솔 로그인과 가입 신청에는 API 키 한도와 별개로 IP와 이메일마다 시도 횟수 한도가 있고, 넘으면 같은 429 rate_limit_exceeded와 Retry-After를 받습니다. 한도 값은 가입과 승인을 보세요.