Rate Limits

이벗 API 게이트웨이는 안정적인 서비스 운영을 위해 인증 방식별 호출 제한을 적용합니다. 한도를 초과하면 HTTP 429 가 반환되며, Retry-After 헤더에 명시된 시간 후 재시도하시면 됩니다.

인증 방식별 제한

응답 헤더로 잔여 확인

모든 응답에는 현재 사용량을 알려주는 헤더가 포함됩니다.

429 응답 처리

HTTP/1.1 429 Too Many Requests
Retry-After: 30
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1718352000

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "요청 한도를 초과했습니다. 30초 후 다시 시도해주세요."
  }
}

Node.js 재시도 예시

async function callWithRetry(url, options, maxRetry = 3) {
  for (let i = 0; i < maxRetry; i++) {
    const res = await fetch(url, options);
    if (res.status !== 429) return res;

    // 429 — Retry-After 만큼 대기 (없으면 지수 백오프)
    const wait = res.headers.get("Retry-After");
    const ms = wait ? parseInt(wait) * 1000 : Math.pow(2, i) * 1000;
    await new Promise(r => setTimeout(r, ms));
  }
  throw new Error("Rate limit retry exhausted");
}

모범 사례

1. 지수 백오프 (Exponential Backoff)

429 응답을 받으면 즉시 재시도하지 말고, 대기 시간을 점차 늘려가며 재시도하세요. 여러 클라이언트가 동시에 차단됐다가 한꺼번에 재시도하는 "썬더링 허드" 문제를 방지할 수 있습니다.

대기 시간:  1초 → 2초 → 4초 → 8초 → 16초 ... (최대 60초)
지터 추가:  ±20% 랜덤 가산 (동시 재시도 분산)

2. 배치 호출 활용

같은 종류 데이터를 N개 가져올 때는 개별 호출 대신 페이징을 활용하세요.

• ❌ GET /orders/{id} × 100번
• ✅ GET /orders?size=100&date_from=... 1번

3. 캐싱

자주 변하지 않는 데이터(상품 마스터, 공급사 정보 등)는 클라이언트에 캐싱하여 호출 자체를 줄이세요. 일반적인 TTL 기준:

• 상품 / 옵션 / 공급사: 30분 ~ 1시간
• 주문 목록: 30초 ~ 1분 (실시간성 필요)
• 재고 수량: 캐싱 비권장 (실시간)

4. 비동기 큐

대량 호출(수천 건 일괄 동기화)은 동기적으로 한 번에 처리하지 말고 작업 큐(예: BullMQ, Sidekiq, Celery)에 분산시켜 분당 한도를 지키며 순차 처리하세요.

5. 변경 감지 후 호출 (Polling 최소화)

같은 endpoint 를 짧은 주기로 반복 호출(polling)하지 마세요. updated_after 같은 변경 시각 필터를 활용해 새로 변경된 데이터만 가져오는 것이 한도와 부하 면에서 유리합니다.

한도 초과 모니터링

반복적으로 429 를 받는 경우 다음을 확인하세요.

• 여러 프로세스(또는 컨테이너)가 동일 키로 동시 호출하고 있지 않은지
• 예기치 못한 무한 루프 / 재시도 폭주가 없는지 (로그·모니터링 확인)
• 현재 요금제 한도가 운영 부하에 맞는지 (Pricing 검토)