API 에러 처리와 Rate Limit 대응: 429 재시도와 지수 백오프

{
  "status": 401,
  "code": "AU002",
  "message": "올바르지 않은 토큰입니다."
}

import os
import random
import time
from collections import deque

import requests

BASE_URL = "https://studio-gateway.zerocall.kr"
RETRYABLE = {429, 500, 502, 503, 504}

session = requests.Session()
session.headers.update({
    "x-api-key": os.environ["KAT_API_KEY"],
    "Content-Type": "application/json",
})


class KatApiError(Exception):
    def __init__(self, status, code, message):
        super().__init__(f"{status} {code} {message}")
        self.status, self.code, self.message = status, code, message


class RateLimiter:
    """period초 동안 max_calls건 이하로 보내는 슬라이딩 윈도"""

    def __init__(self, max_calls=1000, period=60.0):
        self.max_calls, self.period = max_calls, period
        self.calls = deque()

    def wait(self):
        now = time.monotonic()
        while self.calls and now - self.calls[0] >= self.period:
            self.calls.popleft()
        if len(self.calls) >= self.max_calls:
            time.sleep(self.period - (now - self.calls[0]))
        self.calls.append(time.monotonic())


limiter = RateLimiter(max_calls=1000)  # 문서 한도 1,200보다 여유 있게


def to_error(resp):
    try:
        body = resp.json()
    except ValueError:
        body = {}
    return KatApiError(body.get("status", resp.status_code), body.get("code"), body.get("message"))


def kat_request(method, path, *, retry=None, max_retries=5, **kwargs):
    if retry is None:
        retry = method.upper() == "GET"  # 기본은 조회만 재시도
    for attempt in range(max_retries + 1):
        limiter.wait()
        try:
            resp = session.request(method, BASE_URL + path, timeout=15, **kwargs)
        except (requests.ConnectionError, requests.Timeout):
            if not retry or attempt == max_retries:
                raise
        else:
            if resp.ok:
                if not resp.content:
                    return None  # 204 No Content
                body = resp.json()
                return body["result"] if isinstance(body, dict) and "result" in body else body
            if not retry or resp.status_code not in RETRYABLE or attempt == max_retries:
                raise to_error(resp)
        delay = min(60.0, 1.0 * 2 ** attempt)
        time.sleep(delay / 2 + random.uniform(0, delay / 2))  # 지수 백오프 + 지터


try:
    groups = kat_request("GET", "/group")
except KatApiError as e:
    if e.code == "AU017":
        print("비즈니스 기능을 쓸 수 없는 그룹이 키에 연결되어 있습니다.")
    raise

const BASE_URL = 'https://studio-gateway.zerocall.kr';
const RETRYABLE = new Set([429, 500, 502, 503, 504]);
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

class KatApiError extends Error {
  constructor(status, code, message) {
    super(`${status} ${code} ${message}`);
    this.status = status;
    this.code = code;
  }
}

async function katRequest(method, path, { body, retry = method === 'GET', maxRetries = 5 } = {}) {
  for (let attempt = 0; ; attempt++) {
    let res;
    try {
      res = await fetch(`${BASE_URL}${path}`, {
        method,
        headers: { 'x-api-key': process.env.KAT_API_KEY, 'Content-Type': 'application/json' },
        body: body ? JSON.stringify(body) : undefined,
        signal: AbortSignal.timeout(15000),
      });
    } catch (networkError) {
      if (!retry || attempt >= maxRetries) throw networkError;
    }
    if (res) {
      if (res.ok) {
        const text = await res.text();
        if (!text) return null; // 204 No Content
        const json = JSON.parse(text);
        return json && typeof json === 'object' && 'result' in json ? json.result : json;
      }
      const err = await res.json().catch(() => ({}));
      if (!retry || !RETRYABLE.has(res.status) || attempt >= maxRetries) {
        throw new KatApiError(err.status ?? res.status, err.code, err.message);
      }
    }
    const delay = Math.min(60000, 1000 * 2 ** attempt);
    await sleep(delay / 2 + Math.random() * (delay / 2)); // 지수 백오프 + 지터
  }
}

katRequest('GET', '/call-history?groupId=1&limit=100')
  .then((page) => console.log(page.total))
  .catch((e) => console.error(e.status, e.code, e.message));

for i in 1 2 3 4 5; do
  code=$(curl -s -o resp.json -w "%{http_code}" \
    "https://studio-gateway.zerocall.kr/group" -H "x-api-key: $KAT_API_KEY")
  case "$code" in
    2*) cat resp.json; break ;;
    429|5*) sleep $((2 ** i)) ;;
    *) cat resp.json; exit 1 ;;
  esac
done

# 주문번호처럼 업무에서 유일한 값으로 외부 ID를 만들면, 재시도해도 같은 값이 나갑니다.
kat_request("POST", "/chat", retry=True, json={
    "chatRoomId": "yyyyyyyyyyyyyyyyyyyyyyyyyyyyyy",
    "content": "예약이 확정되었습니다.",
    "externalMessageId": "order-20261029-0001-confirm",
})