요청 제한

API 호출이 제한되면 HTTP 429 Too Many Requests와 응답 본문의 code: "RATE_LIMIT_EXCEEDED"가 반환됩니다.

호출 한도 확인하기

API 키 생성 시 제안되는 한도는 직전 1시간 동안 10,000회입니다. 키에 적용된 요청 수와 시간 창은 API 키 정책에서 확인합니다. 용도별로 키를 나누고 불필요한 반복 조회를 줄입니다. 목록을 조회할 때는 해당 엔드포인트의 페이지네이션을 사용합니다.

잘못된 키로 인증을 반복하면 같은 IP의 요청이 일시적으로 제한될 수 있습니다. 401이 발생하면 반복 호출을 중단하고 키의 형식·유효기간·활성 상태를 확인합니다.

429 응답 처리하기

대기 시간을 점진적으로 늘려 재시도합니다. 아래 재시도 횟수와 대기 시간은 예시이며 서비스의 조회 주기에 맞춰 조정합니다.

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 - 1), 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 호출 재시도 한도를 초과했습니다.');
}

호출량과 실행 중인 작업을 확인한 후에도 제한이 계속되면 문의하기로 대상 엔드포인트·발생 시각·오류 응답을 전달합니다.