요청 제한

EasterAd Core API는 서버 안정성과 보안을 유지하기 위해 2계층(Two-Tier) 요청 제한 정책을 운영합니다. 설정된 한도를 초과하거나 비정상적인 접근이 감지되면 HTTP 상태 코드 429 Too Many Requests와 함께 에러 코드 RATE_LIMIT_EXCEEDED가 반환됩니다.

1. 2계층 요청 제한 모델 비교

구분	1. API 키별 처리율 한도	2. IP 기반 인증 실패 록아웃
적용 대상	개별 API 키 단위	요청자의 공인 IP 주소 단위
측정 방식	슬라이딩 윈도우 (Sliding Window)	최근 N초간 발생한 401 실패 횟수
기본 한도	시간당 10,000회 (3,600초) ※ 조정 가능	비공개 고정 보안 임계치
초과 원인	정상 API 호출 빈도 급증	잘못된 키/형식으로 반복 호출 (무차별 대입 의심)
영향 범위	해당 키를 사용하는 요청만 429 반환	해당 IP에서 오는 모든 요청(정상 키 포함) 일시 차단
해제 방식	호출 빈도가 창(Window) 내로 내려오면 즉시 정상화	일정 쿨다운 시간 경과 후 자동 차단 해제

2. 세부 동작 메커니즘

1) 키별 슬라이딩 윈도우 (Sliding Window)

롤링 윈도우 방식: “매시 0분 정각 리셋” 방식이 아니라, 호출 시점 기준 직전 3,600초 동안의 총 호출 수를 연속적으로 평가합니다. 따라서 정각에 트래픽이 몰리더라도 한도가 리셋되지 않습니다.
키 분리 권장: 대시보드에서 용도별(예: 잔액 모니터링 봇용, 회계 대사용)로 별도의 API 키를 발급하세요. 한 봇의 트래픽 급증이 다른 비즈니스 자동화 시스템을 마비시키는 현상을 방지할 수 있습니다.

2) IP 기반 인증 실패 록아웃 (Brute-force 방어)

잘못된 형식의 키나 만료된 키로 인해 401 Unauthorized 실패가 짧은 시간에 반복되면, 시스템은 계정 탈취 시도로 판단하여 해당 IP의 모든 인증 요청을 일시적으로 전면 차단합니다.
차단 상태에서는 올바른 API 키를 보내더라도 429 RATE_LIMIT_EXCEEDED로 거부됩니다.
따라서 클라이언트 애플리케이션에서 401 오류를 받았을 때는 절대 짧은 주기로 재시도 루프를 돌리지 말고 즉시 호출을 중단한 뒤 키 상태를 점검해야 합니다.

3. 안정적인 클라이언트를 위한 지수 백오프 전략

429 응답을 받았을 때 서버와 클라이언트를 보호하기 위한 모범 구현 패턴입니다.

지수 백오프 + 랜덤 지터(Jitter) 알고리즘 (TypeScript 예시)

async function callApiWithBackoff<T>(
    requestFn: () => Promise<T>,
    maxRetries = 5
): Promise<T> {
    let attempt = 0;
    let baseDelayMs = 1000; // 1초부터 시작

    while (attempt < maxRetries) {
        try {
            return await requestFn();
        } catch (error: any) {
            // 429 에러인 경우에만 재시도 진행
            if (error?.statusCode === 429 && attempt < maxRetries - 1) {
                attempt++;
                // 지수 증가: 1s, 2s, 4s, 8s... (최대 30s 상한)
                const exponentialDelay = Math.min(baseDelayMs * Math.pow(2, attempt), 30000);
                // 동시 요청 쏠림 방지를 위한 무작위 지터(Jitter) 추가
                const jitter = Math.random() * 500;
                const totalWaitMs = exponentialDelay + jitter;

                console.warn(`[EasterAd] 429 Rate Limit 감지. ${totalWaitMs}ms 후 재시도 (${attempt}/${maxRetries})`);
                await new Promise(resolve => setTimeout(resolve, totalWaitMs));
                continue;
            }
            throw error;
        }
    }
    throw new Error('API 호출 재시도 한도를 초과했습니다.');
}

트래픽 최적화 팁

페이지네이션 최대화: 충전 이력 등 목록 조회 시 limit=100을 사용하여 전체 호출 횟수를 1/5 수준으로 줄이세요.
폴링 주기 최적화: 실시간성이 불필요한 대시보드 연동은 5분~1시간 주기의 배치성 폴링을 권장합니다.

다음 단계

자동화 레시피: 잔액 모니터링, 이력 대사, 캠페인 현황 조회의 실제 연동 코드를 확인합니다.
안정성 정책: API 하위 호환성 원칙과 스키마 변경 공지 규칙을 알아봅니다.