API Rate Limit 정책 안내

API Rate Limit 정책은 안정적이고 공정한 서비스 제공을 목표로 합니다. 과도한 요청으로 인한 서버 부하를 방지하고, 모든 사용자가 원활하게 API를 이용할 수 있도록 하기 위해 도입되었습니다.

📘

API Rate Limit 정책 시행 안내

안정적인 서비스 이용을 위해 Rate Limit 정책이 단계적으로 시행됩니다.

유예 기간 (2025년 3월 1일 시작): 해당 기간은 변경될 정책에 적응하고 API 사용량을 조절할 수 있도록 마련되었습니다.
확정된 Rate Limit 규칙이 공지되며, 응답 헤더를 통해 예상 결과를 미리 확인하실 수 있습니다. 실제 요청 차단은 유예 기간 동안 적용되지 않습니다.

활성 (2025년 9월 1일 시작): Rate Limit 규칙이 완전히 적용되어, 제한 초과 요청은 HTTP 429 오류와 함께 거부됩니다.

현재는 유예 기간 입니다.


API Rate Limit 규칙

API Rate Limit 규칙은 Fixed Window Counter 알고리즘을 따릅니다. 특정 시간 창(예: 1분) 내에 허용되는 요청 수를 제한하는 방식이며 시간 창이 끝나면 카운터를 0으로 초기화합니다.

속도 제한을 위해 관리되는 카운터는 사용자 및 API 별 요청량을 추적합니다. 이는 동일한 사용자라도 /a API 를 호출하는 횟수와 /b API 를 호출하는 횟수는 각각 별도의 카운터에 기록 및 관리되어 서로의 API 요청에 영향을 주지 않습니다.


API 별 요청 횟수

대부분의 API는 분당 600회의 요청 제한이 적용되지만, 다음 API 목록은 분당 300회의 요청 제한이 적용됩니다. 제한 횟수를 초과하면 HTTP 429 (Too Many Requests) 오류가 발생하니 유의하시기 바랍니다.

APIMethodEndpoint
문서 리스트 조회GET/documents
서명 요청POST/documents
템플릿으로 서명 요청POST/documents/request-with-template
템플릿으로 임베디드 초안 생성POST/embedded-drafts/create-with-template
템플릿 생성POST/templates
파일 업로드POST/files

Rate Limit 관련 응답 헤더

API 요청에 대한 응답에는 현재 Rate Limit 상태를 나타내는 헤더 정보가 포함됩니다. 이를 통해 현재 사용 가능한 요청 횟수와 제한 관련 정보를 확인할 수 있습니다.

curl -i https://api.modusign.co.kr/user/...
...
> HTTP/2 200
> x-ratelimit-limit: 600
> x-ratelimit-remaining: 400
> x-ratelimit-reset: 1620235582
...
응답 헤더설명예시 값
X-RateLimit-Limit해당 엔드포인트의 최대 허용 요청 수600
X-RateLimit-Remaining현재 남은 요청 가능 횟수400
X-RateLimit-ResetRate Limit이 초기화되는 시간(Unix 타임스탬프)1620235582
X-Retry-After요청을 다시 시도하기 전에 기다려야 하는 시간(초) 형식
(요청 제한 초과 시 제공)
35


사용량 초과 시 대응 (조치)

API 요청 제한 초과 시 HTTP 429(Too Many Requests) 오류X-Retry-After 헤더가 응답 됩니다. 이 헤더는 다음 요청을 시도하기 전에 얼마나 기다려야 하는지를 초 단위로 알려줍니다. 예를 들어, Retry-After: 60이라면, 60초 후에 다시 요청을 시도하실 수 있습니다.

👍

Rate Limit에 대비하여 API 요청 시 다음과 같은 방법을 권장드립니다.

연속된 요청 사이에 적절한 지연 시간을 두어 Rate Limit을 초과하지 않도록 합니다. 예를 들어, 분당 300회의 요청이 허용되는 엔드포인트의 경우, 각 요청 사이에 최소 200밀리초의 간격을 두는 것이 좋습니다.

만약 해당 오류를 응답 받으셨을 경우, 다음과 같은 재시도 전략을 권장드립니다:

  • 지수 백오프(Exponential Backoff): 초기 지연 시간부터 시작하여 재시도할 때마다 지연 시간을 지수적으로 증가시키는 방법입니다. 예를 들어, 첫 번째 재시도는 1초 후, 두 번째는 2초 후, 세 번째는 4초 후 등으로 지연 시간을 늘려갑니다. 이를 통해 서버에 가해지는 부하를 줄이고 성공적인 요청 가능성을 높일 수 있습니다.
const axios = require('axios');
const axiosRetry = require('axios-retry');

axiosRetry(axios, {
  retries: 3, // 최대 재시도 횟수 설정
  retryDelay: axiosRetry.exponentialDelay, // 지수 백오프 방식의 지연 시간 설정
  retryCondition: axiosRetry.isRetryableError, // networkError 또는 5xx 에러에 대해 재시도
});

async function fetchData() {
  try {
    const response = await axios.get('https://api.modusign.co.kr/user');
    console.log('데이터:', response.data); // 성공 시 데이터 출력
  } catch (error) {
    console.error('요청 실패:', error.message); // 실패 시 에러 메시지 출력
  }
}

fetchData();

@Configuration
public class RetryConfig {
    @Bean
    public RetryTemplate retryTemplate() {
        // 재시도 정책 설정: 최대 5번 시도
        SimpleRetryPolicy retryPolicy = new SimpleRetryPolicy();
        retryPolicy.setMaxAttempts(5);

        // 지수 백오프 정책 설정
        ExponentialBackOffPolicy backOffPolicy = new ExponentialBackOffPolicy();
        backOffPolicy.setInitialInterval(2000); // 초기 간격 2초
        backOffPolicy.setMultiplier(2.0); // 배수: 2배씩 증가
        backOffPolicy.setMaxInterval(30000); // 최대 간격 30초

        // RetryTemplate에 정책 설정
        RetryTemplate retryTemplate = new RetryTemplate();
        retryTemplate.setRetryPolicy(retryPolicy);
        retryTemplate.setBackOffPolicy(backOffPolicy);

        return retryTemplate;
    }
}

@Service
public class ApiService {
    private final RestTemplate restTemplate;
    private final RetryTemplate retryTemplate;

    @Autowired
    public ApiService(RetryTemplate retryTemplate) {
        this.restTemplate = new RestTemplate();
        this.retryTemplate = retryTemplate;
    }

    public String fetchData() {
        return retryTemplate.execute(context -> {
            try {
                return restTemplate.getForObject("https://api.modusign.co.kr/user", String.class);
            } catch (RestClientException e) {
                throw e;
            }
        });
    }
}


문의 사항

Rate Limit 정책에 대한 문의나 지원이 필요하신 경우, 고객 지원 센터로 연락주시기 바랍니다. 저희는 고객 여러분께 최상의 서비스를 제공하기 위해 최선을 다하고 있습니다. Rate Limit 정책 도입에 대한 이해와 협조에 감사드리며, 앞으로도 지속적인 관심과 이용 부탁드립니다. (정책은 서비스 상황에 따라 변경될 수 있으며, 필요한 경우 안내를 통해 정보를 제공할 예정입니다.)