API를 사용할 때 두 종류의 제한이 적용된다.
API 호출 제한(rate limit)이란 분 당 호출할 수 있는 API 호출 횟수를 의미한다. 사용자의 API 호출 수가 제한값을 초과하면 HTTP 429 코드를 반환하여 요청이 실패한다.
| HTTP Status Code | code | description |
|---|---|---|
| 429 | TOO_MANY_REQUESTS | API rate limit exceeded |
{ "code": "TOO_MANY_REQUESTS", "description": "API rate limit exceeded"}API 호출 제한은 요금제에 따라 다르게 적용된다.
사용할 수 있는 Scope은 상품에 따라 다르며, 각 상품 별 사용할 수 있는 Scope은 Scope 목록를 참고한다.
| Product | Plan | Rate Limit |
|---|---|---|
| 네이버웍스 코어 | Free | API당 60 requests/min |
| 네이버웍스 코어, 웍스 드라이브 | Lite, Standard, Standard Plus | API당 240 requests/min |
| 경영지원 | 결재, 근태, 급여, 재무 | API당 240 requests/min |
다음은 상품과 관계없이 동일하게 Rate Limit이 동일하게 적용된다.
| API or Scope | Rate Limit |
|---|---|
| Bot이 포함된 메시지방 생성 | 10 requests/min |
| board board.read group.note group.note.read task task.read | API당 60 requests/min |
| audit audit.read monitoring.read | API당 10 requests/min |
호출 제한이 적용된 API를 호출하면 다음과 같이 응답 헤더에 네 가지 파라미터가 추가되어 현재 API 호출 수, 적용된 Rate Limit 값, 남은 API 호출 수, 갱신까지 남은 시간을 알 수 있다.
| Response Header | Description |
|---|---|
| rateLimit-ssed | 기준 시간 단위 API 호출 수 |
| rateLimit-limit | 적용된 Rate Limit값 |
| rateLimit-remaining | 기준 시간 단위 남은 API 호출 수 |
| rateLimit-reset | 기준 시간 갱신까지 남은 시간(단위: sec) |
참고
파일 다운로드 URL 조회 API를 호출하면 HTTP 302가 반환되므로 응답 헤더에 호출 제한 파라미터가 포함되지 않는다. 이 API는 파일 업로드/다운로드에서 확인할 수 있다.
API 호출이 제한되면 HTTP 429 코드를 처리하고 실패한 요청을 재시도하면서 API 요청 횟수를 줄여야 한다. 동일한 요청을 캐시로 처리하면 불필요한 API 요청을 줄일 수 있다.
클라이언트 앱에서 API 호출 제한을 고려해 적절하게 처리하지 않으면 의도하지 않은 오류로 인해 앱이 정상적으로 작동하지 않을 수 있다. 따라서, 우선 클라이언트 앱에서 실행하는 API 호출 횟수를 제한해야 한다. 사용자 정보 등 자주 변경되지 않는 데이터는 캐시로 처리한다. 조회하려는 데이터의 일부가 이전 API 응답에 이미 포함되어 있는 경우도 있으므로, 이를 고려해 API를 호출한다. 특히, 요청을 재시도하는 로직이 있으면 요청 재시도 간격을 충분히 늘려 불필요한 동작으로 제한값에 도달하지 않도록 주의한다.
동시 접속 가능 요청 수는 5이며 허용된 동시 접속 요청 수를 넘으면 API 호출에 실패할 수 있다.
| HTTP Status Code | code | description |
|---|---|---|
| 429 | TOO_MANY_REQUESTS | Concurrent access fail |
{ "code": "TOO_MANY_REQUESTS", "description": "Concurrent access fail"}주의
일부 API에는 다른 제한값이 적용될 수 있다.