서비스의 안정성과 공정한 사용을 보장하기 위해, Caret은 클라이언트가 특정 시간 내에 API에 요청할 수 있는 횟수를 제한합니다. 요청 제한은 API 키당 적용되며 엔드포인트와 구독 플랜에 따라 다릅니다.

​
기본 제한

플랜분당 요청 수분당 웹훅 수
무료6020
프로12040
엔터프라이즈300100
일부 리소스 집약적인 작업은 더 낮은 특정 제한이 있을 수 있으며, 이는 관련 API 레퍼런스 섹션에 문서화됩니다.

​
요청 제한 헤더

API 요청을 할 때, Caret은 요청 제한 사용량을 추적하는 데 도움이 되는 여러 헤더를 응답에 포함합니다:
헤더설명
X-RateLimit-Limit현재 시간 창에서 허용되는 최대 요청 수
X-RateLimit-Remaining현재 시간 창에서 남은 요청 수
X-RateLimit-Reset현재 요청 제한 창이 재설정되는 시간 (Unix 시간)
예시 응답 헤더: 
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 56
X-RateLimit-Reset: 1672527600

​
요청 제한 오류 처리

요청 제한을 초과하면, API는 429 Too Many Requests 상태 코드로 응답합니다. 응답 본문에는 상황을 설명하는 오류 메시지가 포함됩니다. 예시 요청 제한 오류 응답: 
{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Please retry after 35 seconds.",
    "retry_after": 35
  }
}

​
요청 제한 처리 모범 사례

  1. 지수 백오프 구현: 429 응답을 받으면 재시도하기 전에 retry_after 필드에 지정된 시간을 기다리세요.
  2. 사용량 모니터링: 각 응답의 요청 제한 헤더를 추적하여 사용량을 모니터링하고 그에 따라 요청 속도를 조정하세요.
  3. 응답 캐싱: 가능한 경우 API 응답을 캐시하여 요청 횟수를 줄이세요.
  4. 배치 작업: 여러 작업을 수행해야 하는 경우, 사용 가능한 배치 엔드포인트를 사용하여 요청 횟수를 줄이세요.

​
예시 재시도 로직

다음은 JavaScript에서 지수 백오프로 재시도 로직을 구현하는 예시입니다: 
async function fetchWithRetry(url, options, maxRetries = 3) {
  let retries = 0;

  while (retries < maxRetries) {
    try {
      const response = await fetch(url, options);

      if (response.status !== 429) {
        return response;
      }

      const data = await response.json();
      const retryAfter = data.error.retry_after || Math.pow(2, retries);

      console.log(`Rate limited. Retrying after ${retryAfter} seconds...`);
      await new Promise((resolve) => setTimeout(resolve, retryAfter * 1000));

      retries++;
    } catch (error) {
      if (retries === maxRetries - 1) {
        throw error;
      }

      const backoffTime = Math.pow(2, retries) * 1000;
      console.log(
        `Error: ${error.message}. Retrying after ${backoffTime / 1000} seconds...`,
      );
      await new Promise((resolve) => setTimeout(resolve, backoffTime));

      retries++;
    }
  }

  throw new Error('Maximum retries reached');
}

​
요청 제한 증가

현재 플랜에서 제공하는 것보다 높은 요청 제한이 필요한 경우 고려해보세요:
  1. 플랜 업그레이드: 상위 티어 플랜은 더 높은 요청 제한을 제공합니다.
  2. 지원팀 문의: 엔터프라이즈 고객은 특정 요구사항에 따른 맞춤형 요청 제한에 대해 지원팀에 문의할 수 있습니다.

​
다음 단계