Rate Limit

호출 제한

구분	제한
시간당	100회
일일	1,000회

제한 기준

• Rate Limit은 API Key 단위로 적용됩니다 (사용자 단위가 아닌, API Key별 카운트).
• 시간당 제한은 매 정시(00분) 기준으로 리셋됩니다 (슬라이딩 윈도우 아님).
• 일일 제한은 자정(UTC 기준) 리셋됩니다.

응답 헤더

모든 API 응답에는 Rate Limit 관련 헤더가 포함됩니다.

헤더	설명
X-RateLimit-Limit	시간당 최대 요청 수 (100)
X-RateLimit-Remaining	남은 요청 수
X-RateLimit-Reset	제한 리셋 시간 (Unix timestamp)

제한 초과 시

호출 제한을 초과하면 429 Too Many Requests 응답이 반환됩니다.

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Please try again later.",
    "retry_after": 3600
  }
}

Retry-After 헤더에 재시도까지 대기해야 할 시간(초)이 포함됩니다.

권장 사항

• 응답의 X-RateLimit-Remaining 값을 모니터링하세요.
• 429 응답을 받으면 Retry-After 헤더 값만큼 대기 후 재시도하세요.
• 오늘의 명언은 하루에 한 번만 변경되므로 클라이언트에서 캐싱하는 것을 권장합니다.
• Exponential backoff 전략을 적용하여 429 응답 시 점진적으로 대기 시간을 늘리세요.

async function fetchWithBackoff(url, headers, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const res = await fetch(url, { headers });
    if (res.status !== 429) return res;

    const retryAfter = parseInt(res.headers.get("Retry-After") || "60", 10);
    const delay = retryAfter * 1000 * Math.pow(2, i);
    await new Promise((r) => setTimeout(r, delay));
  }
  throw new Error("Rate limit exceeded after max retries");
}

응답 헤더 예시

정상 응답 시

HTTP/1.1 200 OK
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1741420800
Content-Type: application/json

429 초과 시

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1741420800
Retry-After: 1823
Content-Type: application/json