Rate Limiting

API의 안정적인 운영을 위해 엔드포인트별로 요청 빈도를 제한합니다. Rate Limit 초과 시 적절한 대응 방법을 안내합니다.

요청 제한 기준

SweetBook API는 3단계 Rate Limiting을 적용합니다. 각 티어는 엔드포인트의 특성에 따라 분류됩니다.

티어	대상 엔드포인트	제한	기준
Auth	`POST /auth/*`	10 req/min	IP 기반
General	Books, Orders, Templates, Webhooks 등	300 req/min	API Key 기반
Upload	AddCover, AddContent (multipart), UploadPhoto	200 req/min	API Key 기반

Auth 엔드포인트는 IP 기반으로 제한되며, 나머지 엔드포인트는 API Key 기반으로 제한됩니다.

Rate Limit 초과 시 응답

요청 제한을 초과하면 429 Too Many Requests 응답이 반환됩니다. 응답 헤더에 Retry-After 값이 포함되며, 해당 시간(초) 이후 재요청할 수 있습니다.

http

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 60

{
  "success": false,
  "message": "Rate limit exceeded. Please retry after 60 seconds.",
  "data": null
}

Best Practices

1. Exponential Backoff 구현

429 응답을 받으면 Retry-After 헤더를 확인하고, 지수 백오프(Exponential Backoff)를 적용하여 재시도하세요.

javascript

async function requestWithRetry(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options);

    if (response.status === 429) {
      const retryAfter = parseInt(response.headers.get('Retry-After') || '60');
      const delay = retryAfter * 1000 * Math.pow(2, attempt);
      console.log(`Rate limited. Retrying after ${delay}ms...`);
      await new Promise(resolve => setTimeout(resolve, delay));
      continue;
    }

    return response;
  }

  throw new Error('Max retries exceeded');
}

2. 응답 캐싱

변경이 잦지 않은 데이터(Templates, Book Specs 등)는 로컬에 캐싱하여 불필요한 API 호출을 줄이세요.

3. 배치 처리

여러 건의 요청이 필요한 경우 가능한 한 배치로 묶어 처리하세요. 예를 들어, 주문 목록을 조회할 때 개별 조회 대신 목록 API를 활용하면 요청 수를 크게 줄일 수 있습니다.