GuidesOneMux

프로덕션 환경의 OpenAI API 오류: 안전한 진단, 재시도 및 복구

OpenAI 인증, 속도 제한, 시간 초과, 서버 오류 및 형식이 잘못된 응답을 진단하고, 무엇을 재시도하거나 수정하거나 복구 절차로 넘길지 결정하는 실무 워크플로를 소개합니다.

AI

요약 · TL;DR

프로덕션 환경의 오류 처리는 모든 요청을 재시도하는 대신 먼저 실패 유형을 분류하는 데서 시작합니다. 이 가이드는 구성 및 할당량 오류와 일시적인 요청 제한, 시간 초과, 서버 오류, 유효하지 않은 응답을 구분하고, 재시도 횟수에 한도를 둔 JavaScript 패턴과 복구 체크리스트를 제공합니다.

핵심 요점

  • 인증, 권한, 잘못된 요청 또는 크레딧 소진 오류는 원인을 먼저 해결하지 않은 채 재시도하지 마세요.
  • 요청 제한이나 과부하가 발생하면 `Retry-After` 헤더가 있을 경우 이를 따르고, 지터를 적용한 지수 백오프로 재시도 횟수를 제한하세요.
  • 시간 초과가 작업 실패를 의미하는 것은 아닙니다. 멱등성이 보장되지 않는 작업을 무작정 반복하지 마세요.
  • 후속 워크플로 상태를 확정하기 전에 정상 응답을 검증하고, 안전하게 복구할 수 있도록 충분한 맥락을 보존하세요.
목차 (6)

프로덕션 원칙: 재시도 전에 실패 유형을 분류하세요

OpenAI API 호출이 실패했을 때 중요한 질문은 단순히 “재시도해야 할까?”가 아닙니다. “이 실패가 일시적이라고 판단할 근거는 무엇이며, 요청이 중복되면 어떤 일이 생길까?”를 물어야 합니다. 프로덕션 워크플로에서는 오류를 분류하고, 횟수에 한도를 둔 조치를 적용하며, 안전하게 진행할 수 없다면 작업 상태를 보존해야 합니다.

OpenAI는 인증 오류, 속도 제한, 크레딧 또는 지출 한도 소진, 서버 오류, 모델 과부하의 원인을 각각 구분해 안내합니다. 상태 코드만으로 원인을 파악하기 어려울 때도 있으므로 오류 코드와 메시지도 확인하세요. 문서에 명시된 원인과 해결 방법은 OpenAI 오류 코드 가이드를 참조하세요.

실패 유형별 분류

증상권장 조치재시도 여부
401 인증 오류API 키가 올바르고 활성 상태인지, 의도한 조직을 사용 중인지 확인하세요. IP 허용 목록을 설정했다면 해당 설정도 확인하세요.아니요. 인증 정보나 액세스 권한을 수정하기 전에는 재시도하지 마세요.
400 잘못된 요청필수 입력, 인코딩, 형식, 크기를 비롯해 메시지와 요청 매개변수를 확인하세요.아니요. 요청을 수정하기 전에는 재시도하지 마세요.
429 속도 제한 또는 “속도를 늦추세요”동시 요청 수나 요청 빈도를 줄이세요. Retry-After가 있으면 이를 따르고, 이후 트래픽을 점진적으로 늘리세요.예. 재시도 정책으로 횟수를 제한하세요.
429 크레딧, 지출 또는 사용량 한도error.code를 확인하고 크레딧을 충전하거나 해당 한도를 해결하세요.아니요. 같은 요청을 반복해도 액세스가 복구되지 않습니다.
500 서버 오류 또는 503 과부하잠시 기다리고, Retry-After가 있으면 이를 따른 뒤 횟수를 제한해 재시도하세요.일반적으로 가능합니다. 단, 안전장치를 적용하세요.
클라이언트 시간 초과 또는 연결 오류네트워크, 프록시, TLS, 방화벽 상태를 확인하고 요청 처리가 완료됐을 가능성이 있는지 판단하세요.경우에 따라 가능합니다. 먼저 중복 실행의 영향을 고려하세요.
성공 상태 코드지만 사용할 수 없는 응답워크플로를 다음 단계로 진행하기 전에 응답 구조와 필수 필드를 검증하세요.자동 재시도는 하지 마세요. 데이터 품질 또는 프로토콜 문제로 별도 처리하세요.

OpenAI 가이드에 따르면 Python의 RateLimitError는 429에, InternalServerError는 503에 해당합니다. 따라서 과부하가 예상과 다른 상태 코드로 반환될 수 있습니다. 어떤 클라이언트를 사용하든 모든 과부하가 429라고 가정하지 말고 상태 코드와 오류 상세 정보를 함께 확인하세요.

횟수를 제한하는 JavaScript 재시도 패턴

사전 조건: 최신 OpenAI JavaScript SDK, 설정된 API 키, 반복 요청을 허용해도 안전한지 판단할 수 있는 워크플로가 필요합니다. 아래 예시는 선택한 일시적 오류만 재시도하는 방법을 보여줍니다. 시간 초과된 요청이 처리되지 않았다는 점을 보장하지는 않습니다.

import OpenAI from "openai";

const client = new OpenAI();

const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

function retryAfterMs(error) {
  const value = error.headers?.get?.("retry-after");
  if (!value) return null;

  const seconds = Number(value);
  if (Number.isFinite(seconds)) return Math.max(0, seconds * 1000);

  const dateMs = Date.parse(value);
  return Number.isNaN(dateMs) ? null : Math.max(0, dateMs - Date.now());
}

function isRetryable(error) {
  const code = error.code;
  if ([
    "credit_balance_exhausted",
    "organization_spend_limit_exceeded",
    "project_spend_limit_exceeded",
    "organization_usage_limit_exceeded",
  ].includes(code)) return false;

  return error instanceof OpenAI.RateLimitError ||
    (error instanceof OpenAI.APIError &&
      [500, 503].includes(error.status));
}

async function createResponseWithRetry(input, maxRetries = 3) {
  for (let attempt = 0; ; attempt++) {
    try {
      return await client.responses.create({
        model: "YOUR_MODEL",
        input,
      });
    } catch (error) {
      if (!isRetryable(error) || attempt >= maxRetries) throw error;

      const exponentialMs = Math.min(10_000, 500 * 2 ** attempt);
      const jitterMs = Math.floor(Math.random() * 250);
      const delayMs = retryAfterMs(error) ?? exponentialMs + jitterMs;
      await sleep(delayMs);
    }
  }
}

YOUR_MODEL은 자리표시자이며 특정 모델을 권장하는 표현이 아닙니다. 이 예시는 재시도 제어를 설명하기 위한 것으로, 모든 SDK 버전이나 엔드포인트에서 동작을 검증한 것은 아닙니다. 설치된 버전에서 SDK가 아래와 같이 응답 헤더를 제공하는지 확인하세요. 그렇지 않다면 지원되는 방식으로 헤더를 읽으세요. 작업이 무기한 대기하지 않도록 재시도 횟수뿐 아니라 워크플로 전체의 기한도 설정하세요.

isRetryable에 인증, 잘못된 요청, 권한 또는 할당량 오류를 추가하지 마세요. 먼저 구성이나 액세스 문제를 해결해야 합니다. 작업별 재시도 예산과 큐 수준의 동시성 제한도 고려하세요. 모든 작업자가 즉시 재시도하면 요청이 급증하는 상황을 더 악화시킬 수 있습니다.

시간 초과와 형식이 잘못된 응답에는 복구 규칙이 필요합니다

시간 초과는 클라이언트가 제시간에 응답을 받지 못했다는 뜻이지, 서버가 작업을 완료했는지 여부를 알려주는 것은 아닙니다. 재시도 전에 작업이 중복 실행되어도 괜찮은지 판단하세요. 후속 조치의 영향이 큰 작업이라면 작업 ID와 처리 상태를 저장하고, 가능하면 후속 쓰기 작업에 멱등성을 적용하세요. 결과가 불확실하다면 무작정 작업을 반복하는 대신 조정이 필요한 상태로 표시하세요.

응답 검증은 별도의 워크플로 단계로 처리하세요. 응답 객체가 존재하는지, 예상한 콘텐츠가 들어 있는지, 구조화된 출력이 파싱되고 애플리케이션 스키마를 충족하는지 확인하세요. 검증에 실패한 응답을 성공 결과로 확정해서는 안 됩니다. 안전한 진단 정보를 기록한 뒤 제한된 수정 또는 검토 절차로 보내세요. 동일한 요청을 반복하면 형식이 잘못된 콘텐츠가 해결될 것이라고 가정하지 마세요.

운영 체크리스트

  1. 타임스탬프와 시간대, 엔드포인트, 모델, HTTP 상태, 오류 유형과 코드, 안전한 요청 상관관계 식별자를 기록하세요.
  2. API 키나 민감한 입력을 로그에 남기지 마세요. 실패를 안전하게 재현하는 데 필요한 요청 정보만 보관하세요.
  3. 최대 시도 횟수, 지연 시간, 지터, 전체 기한을 설정해 일시적인 오류만 재시도하세요.
  4. Retry-After가 제공되면 이를 따르세요. 요청 제한이 계속되면 요청 속도를 더 낮추세요.
  5. 재시도 소진 상태와 영구 실패를 구분해 운영자가 확인하고 재실행 가능한 작업을 다시 처리할 수 있도록 하세요.
  6. 오류가 지속되면 모델, 오류 메시지와 코드, 비밀 정보를 제거한 요청 데이터와 헤더, 타임스탬프와 시간대 및 기타 관련 맥락을 수집하세요. OpenAI는 지원팀에 이러한 정보를 제공할 것을 권장합니다.

결론

신뢰할 수 있는 OpenAI API 워크플로는 일시적인 서비스 부하와 구성 또는 한도 변경이 필요한 오류를 구분합니다. 요청 제한과 서비스 오류는 신중하게 재시도하고, 인증 및 요청 오류는 수정하세요. 시간 초과와 유효하지 않은 출력은 명시적인 복구 상태로 처리해야 합니다. 이렇게 오류를 분류하면 재시도 루프가 단일 호출 실패를 더 큰 프로덕션 장애로 키우는 일을 방지할 수 있습니다.

FAQ

모든 OpenAI API 429 응답을 재시도해야 하나요?

아니요. 속도 제한 응답은 요청 간격을 조정하고, 시도 횟수에 한도를 두며, `Retry-After`가 있으면 이를 따라 재시도하세요. 크레딧 소진이나 지출 또는 사용량 한도로 발생한 429는 해당 한도를 해결해야 합니다. 호출을 반복해도 액세스가 복구되지 않습니다. 오류 코드를 확인하세요.

OpenAI API 시간 초과가 발생하면 워크플로에서 어떻게 처리해야 하나요?

결과가 불확실한 상태로 취급하세요. 처리가 완료됐더라도 클라이언트에서는 시간 초과가 발생했을 수 있습니다. 재시도 전에 중복 실행의 영향을 고려하고, 가능하면 후속 작업에 멱등성을 적용하세요. 결과가 모호한 작업은 조정 절차로 넘기세요.

API가 형식이 잘못된 응답을 반환하면 어떻게 해야 하나요?

응답을 저장하거나 이를 바탕으로 작업하기 전에 응답 구조와 필수 필드를 검증하세요. 작업을 성공 상태로 처리하지 말고 안전한 진단 정보를 기록한 다음, 동일한 요청을 자동으로 반복하는 대신 통제된 수정 또는 검토 절차를 사용하세요.

503은 429와 같은 의미인가요?

아니요. OpenAI에서 제공한 가이드는 429 속도 제한 응답과 503 모델 과부하 응답을 서로 다른 경우로 설명합니다. 클라이언트는 과부하가 항상 429로 표시된다고 가정하지 말고, 상태 코드와 오류 상세 정보를 확인해 두 경우를 적절히 처리해야 합니다.

관련 글