OpenAI 429/Rate Limit 재시도·백오프 실전 가이드

// retryFetch.ts

type RetryOptions = {
  maxAttempts: number;      // 총 시도 횟수 (최초 1회 포함)
  baseDelayMs: number;      // 예: 200
  maxDelayMs: number;       // 예: 10_000
  timeoutMs: number;        // 예: 30_000
};

function sleep(ms: number) {
  return new Promise((r) => setTimeout(r, ms));
}

function parseRetryAfterMs(res: Response): number | null {
  const v = res.headers.get("retry-after");
  if (!v) return null;

  // Retry-After는 초 단위 숫자 또는 HTTP-date일 수 있음
  const asNum = Number(v);
  if (!Number.isNaN(asNum)) return Math.max(0, asNum * 1000);

  const asDate = Date.parse(v);
  if (!Number.isNaN(asDate)) return Math.max(0, asDate - Date.now());

  return null;
}

function isRetryableStatus(status: number) {
  return status === 429 || status === 408 || status === 409 || (status >= 500 && status <= 504);
}

function computeFullJitterDelayMs(attempt: number, baseDelayMs: number, maxDelayMs: number) {
  // attempt: 1,2,3... (재시도 횟수 기준)
  const cap = Math.min(maxDelayMs, baseDelayMs * Math.pow(2, attempt));
  return Math.floor(Math.random() * cap);
}

export async function retryFetch(
  input: RequestInfo | URL,
  init: RequestInit,
  opt: RetryOptions
) {
  let lastErr: unknown;

  for (let attempt = 1; attempt <= opt.maxAttempts; attempt++) {
    const ac = new AbortController();
    const t = setTimeout(() => ac.abort(), opt.timeoutMs);

    try {
      const res = await fetch(input, { ...init, signal: ac.signal });
      clearTimeout(t);

      if (res.ok) return res;

      if (!isRetryableStatus(res.status) || attempt === opt.maxAttempts) {
        // 재시도 비대상 또는 마지막 시도
        return res;
      }

      const ra = parseRetryAfterMs(res);
      const backoff = computeFullJitterDelayMs(attempt, opt.baseDelayMs, opt.maxDelayMs);
      const delay = ra !== null ? Math.max(ra, backoff) : backoff;

      // 필요하다면 여기서 res.text()를 읽어 에러 바디를 로그로 남기되,
      // 민감정보가 포함될 수 있으니 필터링하세요.
      console.warn("retryable status", {
        status: res.status,
        attempt,
        delayMs: delay,
      });

      await sleep(delay);
      continue;
    } catch (err) {
      clearTimeout(t);
      lastErr = err;

      // 네트워크 에러/Abort는 일시적일 수 있어 재시도
      if (attempt === opt.maxAttempts) throw err;

      const delay = computeFullJitterDelayMs(attempt, opt.baseDelayMs, opt.maxDelayMs);
      console.warn("fetch error, will retry", { attempt, delayMs: delay, err: String(err) });
      await sleep(delay);
    }
  }

  throw lastErr;
}

import { retryFetch } from "./retryFetch";

const res = await retryFetch(
  "https://api.openai.com/v1/responses",
  {
    method: "POST",
    headers: {
      "content-type": "application/json",
      authorization: `Bearer ${process.env.OPENAI_API_KEY}`,
    },
    body: JSON.stringify({
      model: "gpt-4.1-mini",
      input: "Summarize this text...",
    }),
  },
  {
    maxAttempts: 6,
    baseDelayMs: 200,
    maxDelayMs: 10_000,
    timeoutMs: 30_000,
  }
);

if (!res.ok) {
  const body = await res.text();
  throw new Error(`OpenAI error status=${res.status} body=${body}`);
}

const data = await res.json();
console.log(data);

class Semaphore {
  private available: number;
  private queue: Array<() => void> = [];

  constructor(count: number) {
    this.available = count;
  }

  async acquire() {
    if (this.available > 0) {
      this.available -= 1;
      return;
    }
    await new Promise<void>((resolve) => this.queue.push(resolve));
  }

  release() {
    this.available += 1;
    const next = this.queue.shift();
    if (next) {
      this.available -= 1;
      next();
    }
  }
}

const openaiSem = new Semaphore(5); // 예: 동시에 5개만

export async function withOpenAIConcurrencyLimit<T>(fn: () => Promise<T>) {
  await openaiSem.acquire();
  try {
    return await fn();
  } finally {
    openaiSem.release();
  }
}

import { withOpenAIConcurrencyLimit } from "./sem";
import { retryFetch } from "./retryFetch";

const res = await withOpenAIConcurrencyLimit(() =>
  retryFetch(
    "https://api.openai.com/v1/responses",
    {
      method: "POST",
      headers: {
        "content-type": "application/json",
        authorization: `Bearer ${process.env.OPENAI_API_KEY}`,
      },
      body: JSON.stringify({ model: "gpt-4.1-mini", input: "..." }),
    },
    { maxAttempts: 6, baseDelayMs: 200, maxDelayMs: 10_000, timeoutMs: 30_000 }
  )
);

import crypto from "crypto";

function makeIdempotencyKey(userId: string, promptHash: string) {
  return crypto.createHash("sha256").update(`${userId}:${promptHash}`).digest("hex");
}

// DB에 (idempotency_key unique)로 저장해 중복 실행 방지