요청 한도

공개 API는 각 API 키 또는 OAuth 액세스 토큰에 1분 단위 요청 버킷을 적용합니다. 한도를 우회하기 위해 키를 더 만드는 것은 지원되지 않으며 자격 증명 또는 계정 제한으로 이어질 수 있습니다.

요금제 한도#

계정에 활성 유료 요금제가 없는 자격 증명은 요청 한도 용량을 받기 전에 403 subscription_required를 반환합니다. 비용이 매우 큰 작업에는 더 낮은 엔드포인트별 한도가 생길 수 있으며, 그런 경우 엔드포인트 레퍼런스에서 명시합니다.

요청 한도 응답#

버킷이 소진되면 API는 다음 헤더와 함께 429 rate_limit_exceeded를 반환합니다.

HTTP/1.1 429 Too Many Requests
Retry-After: 17
X-RateLimit-Limit: 600
X-RateLimit-Remaining: 0
X-Request-Id: 6c0b2f2e-...
Content-Type: application/json

Retry-After는 기다려야 하는 최소 초입니다. 성공 응답에는 현재 남은 할당량 카운터가 포함되지 않으므로 반복적인 429를 통해 한도를 알아내려 하지 말고 애플리케이션이 자체 동시성을 제어해야 합니다.

재시도 구현#

무작위 지터가 있는 지수 백오프를 사용하고, 더 큰 Retry-After 값을 지키며, 전체 시도 횟수를 제한합니다.

async function requestWithRetry(url: string, init: RequestInit, attempts = 4) {
  for (let attempt = 0; attempt < attempts; attempt += 1) {
    const response = await fetch(url, init);
    if (response.status !== 429 && response.status < 500) return response;

    if (attempt === attempts - 1) return response;
    const retryAfter = Number(response.headers.get("retry-after") ?? 0) * 1_000;
    const exponential = 500 * 2 ** attempt;
    const jitter = Math.random() * 250;
    await new Promise((resolve) =>
      setTimeout(resolve, Math.max(retryAfter, exponential + jitter)),
    );
  }
  throw new Error("unreachable");
}

POST, PATCH, DELETE에서는 모든 네트워크 또는 서버 재시도에 동일한 유효 Idempotency-Key를 유지하세요. 새로운 멱등성 키는 이미 완료된 부작용을 반복할 수 있습니다.

요청량 줄이기#

• 실시간 최신성이 필요하지 않은 계정, 사이트, 설정 읽기를 캐시합니다.
• 매우 작은 페이지를 반복 요청하지 말고 페이지당 최대 100개 레코드를 요청합니다.
• 대화, 리드, 도메인 상태 또는 브로드캐스트를 폴링하는 대신 웹훅 이벤트를 처리합니다.
• API 키별 워커 동시성을 제한합니다. 여러 서버리스 호출의 버스트는 같은 버킷을 공유합니다.
• 서로 다른 서비스에는 격리와 감사를 위해 별도 키를 사용하되 한 작업의 용량을 늘리는 용도로 사용하지 않습니다.

재시도 판단표#

지속적인 작업량이 실제로 요금제 버킷을 초과한다면 무제한 재시도 루프를 추가하지 말고 폴링을 줄이고 작업을 묶거나 대표 요청 ID와 예상 트래픽을 포함해 지원팀에 문의하세요.