API 호출 제한 무시하면 자동화 하루가 멈춥니다

Pipedeck 실제 화면

작성자

카테고리:

API 호출 제한(429) 무시하면 자동화가 하루 통째로 멈춥니다

2026년 10월 6일 기준으로 내 크론이 서버에 70개, 노트북에 9개 돌고 있다. 이걸 다 내가 손으로 관리한다. 어느 날 새벽에 크론 작업 두 개가 겹쳐서 같은 API 엔드포인트에 동시에 요청을 쏟았다. 상태 코드 429. API 호출 제한 걸렸다는 응답이 떨어졌고, 그날 하루 치 데이터 수집이 통째로 날아갔다.

429가 무서운 건 에러 자체가 아니라 그 뒤의 연쇄 작용이다. 크론이 429를 만나면 보통 스크립트가 에러를 뱉고 종료한다. 그러면 그 뒤에 실행돼야 할 작업들도 다 의미 없어진다. 파이프라인 중간이 뚫린 거나 마찬가지다.

상태 코드 429가 터졌을 때 자동화 파이프라인이 죽는 패턴

내가 겪은 패턴은 이랬다. 오전 6시 크론이 A 작업을 실행하고, 6시 1분에 B 작업이 실행된다. 그런데 A 작업이 처리량이 많아 6시 1분까지 끝나지 않았다. B 작업은 A가 쓰는 API와 같은 계정의 토큰을 쓴다. 두 작업이 동시에 API를 때리니 429가 터졌고, B 작업은 첫 요청에서 바로 종료됐다.

문제는 이걸 내가 아침에 일어나서야 발견했다는 거다. 자동화가 실패한 채로 몇 시간이 흘렀고, 그날 리포트는 비어 있었다.

응답 헤더에서 남은 API 호출 횟수와 재시도 시점 확인하기

429 응답이 오면 대부분의 API 제공자가 응답 헤더에 정보를 남긴다. X-RateLimit-Remaining, Retry-After 같은 헤더다. 이걸 읽으면 “지금 몇 번 남았는지”, “언제 다시 요청해도 되는지”를 알 수 있다.

이걸 무시하고 그냥 sleep(60) 같은 식으로 고정 대기를 걸면, 운 좋으면 넘어가고 운 나쁘면 또 429를 맞는다. 응답 헤더를 파싱해서 동적으로 대기 시간을 잡는 게 기본이다.

API 호출 제한에 걸려도 멈추지 않는 재시도 로직 세팅

초창기에는 429가 오면 무한 재시도를 걸었다. while 루프 안에 sleep(1)을 넣고, 200이 올 때까지 기다리는 식이었다. 이게 API 제공자한테 DoS 공격처럼 보였을 거다. 다행히 계정이 영구 밴당하진 않았지만, 경고 메일을 받은 적이 있다.

지수 백오프(Exponential Backoff)로 안전하게 재시도하는 법

그 뒤로 재시도 간격을 2초, 4초, 8초로 늘리는 지수 백오프 방식을 적용했다. 최대 3회까지만 재시도하고, 그래도 안 되면 에러를 기록하고 작업을 종료한다. 3회를 넘기면 API 제공자 입장에서도 비정상 트래픽으로 간주할 수 있어서다.

Retry-After 헤더가 있으면 그 값을 우선으로 쓴다. 헤더가 없을 때만 지수 백오프로 넘어가는 식이다.

function fetchWithRetry(url, options, maxRetries = 3) {
  let attempt = 0;
  let delay = 2000;

  async function tryFetch() {
    const res = await fetch(url, options);

    if (res.status === 429) {
      if (attempt >= maxRetries) {
        logError('429 max retries reached', url);
        return null;
      }

      const retryAfter = res.headers.get('Retry-After');
      const wait = retryAfter ? parseInt(retryAfter) * 1000 : delay;

      attempt++;
      delay *= 2;

      await sleep(wait);
      return tryFetch();
    }

    return res;
  }

  return tryFetch();
}

재시도 횟수와 간격은 몇 번, 어떻게 잡아야 안전한가?

3회, 2초에서 시작하는 게 내가 실측에서 찾은 안정값이다. 5회 이상 재시도하면 API 제공자쪽에서 임계치 알림이 뜰 수 있고, 1초 간격으로 시작하면 너무 빨라서 또 막힌다. 2초, 4초, 8초면 세 번째 재시도까지 총 14초를 기다리게 되는데, 이 정도면 대부분의 API 호출 제한 윈도우가 풀린다.

물론 API마다 제한 정책이 다르니까 이 값은 기준점이지 정답이 아니다. 응답 헤더에 명시된 Retry-After가 있으면 그걸 따라가는 게 맞다.

Pipedeck 실제 화면

1인 운영을 위한 API 호출 큐 실전 세팅법

재시도 로직만으로는 부족하다. 429가 떴다는 건 이미 한 번에 너무 많은 요청을 보냈다는 뜻이다. 요청 자체를 줄여야 한다. 그래서 큐를 도입했다.

보통 큐 하면 Redis나 RabbitMQ를 떠올리는데, 1인 스튜디오에서 굳이 그렇게 무거운 걸 올릴 필요가 없었다. 내 노트북에 SQLite 파일 하나면 충분했다.

Redis 없이 SQLite/로컬 파일로 간단히 큐를 만드는 법

구조는 단순하다. API 요청을 직접 날리지 않고 SQLite 테이블에 적재한다. 컬럼은 url, payload, status, created_at 네 개면 된다. 요청이 들어오면 status를 ‘pending’으로 insert 한다. 실제 API 호출은 별도 크론이 담당한다.

CREATE TABLE IF NOT EXISTS api_queue (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  url TEXT NOT NULL,
  payload TEXT,
  status TEXT DEFAULT 'pending',
  created_at TEXT DEFAULT (datetime('now', 'localtime'))
);

요청을 큐에 넣는 쪽은 API를 호출하지 않는다. 그냥 DB에 insert 한다. 이렇게 하면 요청이 몰려도 API 호출 제한에 걸릴 일이 없다. 큐에 쌓일 뿐이다.

큐에 쌓인 요청을 순차적으로 빼먹는 크론 작업 구성

실제 API 호출은 별도 크론이 1분마다 실행된다. 이 크론이 하는 일은 이렇다.

  1. API 남은 호출 횟수를 확인한다 (응답 헤더 또는 별도 엔드포인트)
  2. status가 ‘pending’인 요청을 남은 횟수만큼만 꺼낸다
  3. API를 호출하고 결과에 따라 status를 ‘done’ 또는 ‘failed’로 업데이트

남은 횟수가 0이면 그냥 종료한다. 다음 크론 실행 때 이어서 처리한다. 이렇게 하면 API 호출 제한을 절대 넘기지 않는다. 큐에 쌓인 요청이 좀 늦게 처리될 뿐, 날아가지는 않는다.

내 경우에는 이 큐 로직을 Pipedeck(https://pipedeck.wallenstein.dev) 운영에 쓰고 있다. 여러 파이프라인이 같은 API를 공유할 때 큐가 없으면 결국 누군가는 429를 맞는다.

Pipedeck 실제 화면

API 토큰 소진과 비용 폭발을 사전에 막는 알림 시스템

429보다 무서운 게 비용 폭발이다. 429는 API가 막아주니까 오히려 안전장치다. 진짜 문제는 429 없이 토큰이 소진되고 과금이 누적되는 경우다.

하루 호출 한도 80% 도달 시 텔레그램/슬랙 알림 받기

예전에 자동화 스크립트의 조건문이 꼬여서 무한 루프가 발생한 적이 있다. 정상이라면 한 번 처리하고 넘어갈 작업이 계속 같은 API를 호출했다. 429도 안 떴다. 호출 한도가 아니라 과금 한도가 문제였으니까. 아침에 확인하니 API 사용량이 전날 대비 기하급수적으로 늘어 있었다.

그 뒤로 로컬에 API 호출 카운트를 누적하는 간단한 로직을 달았다. 매 요청마다 +1씩 올리고, 하루 호출 수가 특정 임계치를 넘으면 텔레그램 봇으로 메시지를 보낸다. 임계치는 대략 하루 예상 호출량의 80% 정도로 잡았다.

// 매 API 호출마다 실행
callCount++;
localStorage.setItem('api_call_count_today', callCount);

if (callCount >= dailyThreshold * 0.8) {
  sendTelegramAlert(
    'API 호출 80% 도달: ' + callCount + '회 / ' + dailyThreshold + '회'
  );
}

알림만 보내고 자동화를 계속 둘 수도 있지만, 나는 알림과 동시에 자동화를 임시 중단시킨다. 카운트가 80%를 넘었다는 건 뭔가 비정상이라는 뜻이니까. 확인하고 수동으로 다시 켜는 게 안전하다.

예기치 않은 루프 에러로 인한 API 과금 폭발 방지하기

루프 에러 방지는 사실 알림보다 근본적인 문제다. 스크립트 시작할 때 최대 반복 횟수를 하드코딩해 둔다. for 루프든 while 루프든 “이 작업은 최대 100번까지만 돈다” 같은 상한을 걸어두는 거다. 상한을 넘으면 강제 종료하고 알림을 보낸다.

이걸 안 해두면 조건문 하나 잘못 짜서 하루 종일 API를 때릴 수 있다. 알림이 와도 이미 과금은 누적된 뒤다. 상한선이 먼저다.

크론 작업에서 API 제한을 회피하는 실전 팁과 한계

큐와 재시도가 있어도 애초에 429가 안 뜨게 스케줄링하는 게 가장 깔끔하다.

크론 주간 스케줄링으로 트래픽 피크 타임 분산시키기

내가 저지른 실수 중 하나가 여러 자동화 파이프라인을 같은 시각에 몰아 넣은 거다. 오전 6시에 데이터 수집, 리포트 생성, 숏폼 제작을 전부 시작하도록 크론을 짰다. 세 작업이 공통으로 쓰는 API가 있어서 정시에 429가 터졌다.

해결책은 단순했다. 시작 시간을 1~2분씩 엇갈리게 배정한 거다. 6시 00분, 6시 02분, 6시 05분. 이 정도 차이면 같은 API를 써도 호출이 겹치지 않는다.

API 제공자의 피크 시간대도 피한다. 대부분의 API는 오후 2시부터 5시가 트래픽 피크다. 이 시간대에는 자동화를 최대한 안 돌린다. 새벽이나 오전으로 몰아서 실행한다.

응답 헤더를 파싱해 다음 호출 시점 동적으로 미루기

가끔은 429가 명시적으로 떨어지지 않고 응답이 그냥 느려지거나 빈 값이 돌아오는 경우가 있다. 사일런트 드랍이라고 부르는 현상이다. 상태 코드는 200인데 응답 본문이 비어 있거나, 평소보다 응답 시간이 비정상적으로 길어진다.

이때는 응답 헤더의 X-RateLimit-Remaining 값을 확인한다. 남은 횟수가 0이거나 1이면, 429를 기다리지 말고 자발적으로 호출을 쉬어야 한다. 응답 시간이 평소 대비 3배 이상 느려도 일단 큐에 쌓아두고 다음 크론까지 미룬다.

사일런트 드랍은 잡기 까다롭다. 에러가 아니니까 자동화가 정상이라고 착각한다. 응답 시간과 응답 본문 길이를 기록해 두고, 평균치에서 벗어나면 경고를 띄우는 식으로 대응하고 있다.

Pipedeck 실제 화면

API 호출 제한 대응 요약 및 1인 빌더를 위한 행동 가이드

지금까지 내가 실제로 쓰고 있는 API 429 대응 세팅을 정리하면 이렇다.

오늘 바로 적용할 수 있는 API 방어 체크리스트

  • 429 응답 시 Retry-After 헤더를 읽어 동적으로 대기
  • 지수 백오프: 2초, 4초, 8초, 최대 3회
  • SQLite 기반 로컬 큐로 요청을 적재하고 크론이 순차 처리
  • API 호출 카운트 추적, 80% 도달 시 텔레그램 알림 후 자동화 임시 중단
  • 루프 상한선 하드코딩, 초과 시 강제 종료
  • 크론 시작 시간 1~2분씩 엇갈려 배정, 피크 시간대 회피
  • 응답 헤더의 남은 호출 횟수를 모니터링, 429 오기 전에 자발적 셧다운

다음 단계: 에러 로깅과 자동 복구 시스템으로 나아가기

지금은 알림이 오면 내가 수동으로 확인하고 자동화를 다시 켠다. 여기서 더 나가면 에러 로그를 구조화해서 쌓고, 429가 아닌 일시적 에러는 자동으로 큐에 재적재하는 복구 로직을 붙이는 게 다음 목표다. 아직 완성하진 못했고, 지금은 알림을 받고 수동으로 대응하는 단계로 운영 중이다.

내가 굴리는 자동화 파이프라인이나 서비스 운영 이야기는 포트폴리오(wallenstein.dev)에서 더 볼 수 있다. 1인으로 돌리다 보면 이런 방어선 없이는 하루도 버티기 어렵다.


글쓴이 정보

1인 빌더 아일리고가 씁니다. 잘된 것도 망한 것도 적습니다. 영상은 제가 만든 ClipSquare 에서 나옵니다.

궁금해할 만한 것들

API 429 에러가 발생하면 자동화 스크립트는 왜 멈추나요?

429 응답을 만나면 대부분의 스크립트는 에러를 뱉고 종료됩니다. 이후에 실행돼야 할 파이프라인 작업들도 연달아 실패하게 됩니다. 파이프라인 중간이 뚫린 것과 같아서 하루 치 데이터가 통째로 날아갈 수 있습니다.

API 429 응답 헤더에서 꼭 확인해야 할 값은 무엇인가요?

X-RateLimit-Remaining과 Retry-After 헤더를 확인해야 합니다. 남은 API 호출 횟수와 언제 다시 요청해도 되는지 알 수 있기 때문입니다. 이 값을 무시하고 고정 대기를 걸면 또다시 429 에러를 맞을 수 있습니다.

지수 백오프(Exponential Backoff) 재시도 간격은 어떻게 설정하나요?

보통 2초, 4초, 8초로 재시도 간격을 늘리며 최대 3회까지만 시도하는 게 안전합니다. 5회 이상 시도하면 API 제공자한테 비정상 트래픽으로 간주될 수 있습니다. 다만 응답 헤더에 Retry-After 값이 있다면 그 값을 최우선으로 따라가야 합니다.

API 호출 큐를 Redis 없이 구축하려면 어떻게 해야 하나요?

SQLite 파일 하나면 1인 스튜디오 수준의 요청 큐를 충분히 만들 수 있습니다. API 요청을 직접 날리지 않고 SQLite 테이블에 url, payload, status, created_at 컬럼으로 적재합니다. 이후 별도의 크론이 순차적으로 큐를 읽어 실제 API 호출을 담당하게 하면 됩니다.