오류 코드 | OpenAI API

이 가이드에서는 API와 공식 Python 라이브러리를 사용할 때 발생할 수 있는 오류 코드를 설명합니다. 개요에 나온 각 오류 코드의 자세한 해결 방법은 해당 섹션에서 확인할 수 있습니다.

API 오류

코드	개요
400 - 잘못된 `service_tier` 인수	원인: 요청에서 지정했거나 최종적으로 결정된 서비스 등급이 프로젝트에서 허용되지 않습니다. 해결 방법: `service_tier`를 프로젝트에서 허용하는 등급으로 설정하거나 프로젝트 설정에서 허용할 서비스 등급을 변경하세요.
401 - 인증 실패	원인: 인증 정보가 유효하지 않습니다. 해결 방법: 올바른 API 키를 사용하고 요청을 보내는 조직을 올바르게 지정했는지 확인하세요.
401 - 잘못된 API 키	원인: 요청에 사용한 API 키가 올바르지 않습니다. 해결 방법: 올바른 API 키를 사용했는지 확인하거나, 브라우저 캐시를 지우거나, 새 키를 생성하세요.
401 - API를 사용하려면 조직의 구성원이어야 함	원인: 계정이 조직에 속해 있지 않습니다. 해결 방법: OpenAI에 문의해 새 조직에 추가해 달라고 요청하거나 조직 관리자에게 조직 초대를 요청하세요.
401 - 허용되지 않은 IP	원인: 요청을 보낸 IP가 프로젝트 또는 조직에 설정된 IP 허용 목록에 없습니다. 해결 방법: 허용된 IP에서 요청을 보내거나 IP 허용 목록 설정을 변경하세요.
403 - 지원되지 않는 국가, 지역 또는 영토	원인: 지원되지 않는 국가, 지역 또는 영토에서 API에 접속하고 있습니다. 해결 방법: 자세한 내용은 지원 국가 및 지역 안내를 참고하세요.
429 - 크레딧 잔액 소진	코드: `credit_balance_exhausted` 원인: 조직의 선불 크레딧을 모두 사용했습니다. 해결 방법: API를 계속 사용하려면 크레딧을 추가하세요.
429 - 요청 한도 도달	원인: 요청을 너무 빠르게 보내고 있습니다. 해결 방법: 요청 간격을 조절하고 `Retry-After` 헤더가 있으면 지정된 대기 시간을 따르세요. 요청 한도 가이드를 참고하세요.
429 - 요청 속도를 낮춰야 함	유형: `rate_limit_error` 코드: `slow_down` 원인: 요청 빈도가 너무 빠르게 증가했습니다. 해결 방법: `Retry-After` 헤더가 있으면 지정된 대기 시간을 따르세요. 요청 빈도를 낮춘 뒤 서서히 높이세요.
429 - 조직 지출 한도 도달	코드: `organization_spend_limit_exceeded` 원인: 조직에 적용되는 지출 한도에 도달했습니다. 해결 방법: 조직 지출 한도를 높이거나 해제하세요.
429 - 프로젝트 지출 한도 도달	코드: `project_spend_limit_exceeded` 원인: 프로젝트에 적용되는 지출 한도에 도달했습니다. 해결 방법: 프로젝트 설정에서 지출 한도를 높이거나 해제하세요.
429 - 조직 사용 한도 도달	코드: `organization_usage_limit_exceeded` 원인: OpenAI가 조직에 부여한 사용 한도에 도달했습니다. 해결 방법: 승인된 사용 한도의 상향을 요청하거나 지원팀에 문의하세요.
500 - 서버에서 요청 처리 중 오류 발생	원인: OpenAI 서버에 문제가 발생했습니다. 해결 방법: 잠시 기다린 뒤 요청을 다시 보내세요. 문제가 계속되면 OpenAI에 문의하세요. 상태 페이지도 확인하세요.
503 - 모델의 일시적 과부하	유형: `service_unavailable_error` 코드: `server_is_overloaded` 원인: 요청한 모델이 일시적으로 과부하 상태입니다. 해결 방법: `Retry-After` 헤더가 있으면 지정된 시간만큼 기다린 뒤 요청을 다시 보내세요.

결제 관련 오류의 구체적인 원인은 error.code에서 확인하세요. 더 포괄적인 분류인 error.type은 여전히 insufficient_quota일 수 있습니다.

결제, 지출 또는 할당량 관련 오류가 발생하면 요청을 다시 보내도 API를 사용할 수 없습니다. 먼저 해당 크레딧을 충전하거나 한도를 조정한 뒤 요청을 보내세요.

WebSocket 모드 오류

Responses API의 WebSocket 모드를 사용할 때는 다음 오류도 발생할 수 있습니다.

previous_response_not_found: 현재 사용 가능한 상태 정보에서 previous_response_id에 해당하는 응답을 찾을 수 없습니다. 전체 입력 컨텍스트를 포함하고 previous_response_id를 null로 설정해 다시 요청하세요.
websocket_connection_limit_reached: 연결 시간이 60분 한도에 도달했습니다. 새 WebSocket 연결을 열고 계속 진행하세요.

Python 라이브러리 오류 유형

Python 라이브러리는 RateLimitError를 429 응답에서, InternalServerError를 503 응답에서 발생시킵니다. 기존 오류 처리기가 요청 제한과 과부하에 대해 둘 중 한 클래스만 처리했다면 두 클래스 모두 처리하고 error.code를 확인하도록 수정하세요. 예를 들어 동영상 처리 중 과부하가 발생하면 이제 503을 반환하며, 이전에는 429를 반환했습니다. 엔드포인트별 변경 사항은 마이그레이션 가이드를 참고하세요.

유형	개요
APIConnectionError	원인: OpenAI 서비스에 연결하는 중 문제가 발생했습니다. 해결 방법: 네트워크 설정, 프록시 구성, SSL 인증서 또는 방화벽 규칙을 확인하세요.
APITimeoutError	원인: 요청 시간이 초과되었습니다. 해결 방법: 잠시 기다린 뒤 요청을 다시 보내세요. 문제가 계속되면 OpenAI에 문의하세요.
AuthenticationError	원인: API 키 또는 토큰이 유효하지 않거나 만료 또는 폐기되었습니다. 해결 방법: API 키 또는 토큰이 올바르고 활성 상태인지 확인하세요. 계정 대시보드에서 새로 생성해야 할 수도 있습니다.
BadRequestError	원인: 요청 형식이 잘못되었거나 토큰 또는 입력과 같은 필수 매개변수가 누락되었습니다. 해결 방법: 오류 메시지에서 구체적인 문제를 확인하세요. 호출하는 API 메서드의 문서를 참고해 유효한 매개변수를 빠짐없이 보내는지 확인하세요. 요청 데이터의 인코딩, 형식 또는 크기도 확인해야 할 수 있습니다.
ConflictError	원인: 다른 요청이 리소스를 업데이트했습니다. 해결 방법: 같은 리소스를 업데이트하려는 다른 요청이 없는지 확인하고 다시 업데이트하세요.
InternalServerError	원인: OpenAI 측에서 문제가 발생했습니다. 해결 방법: 잠시 기다린 뒤 요청을 다시 보내세요. 문제가 계속되면 OpenAI에 문의하세요.
NotFoundError	원인: 요청한 리소스가 존재하지 않습니다. 해결 방법: 올바른 리소스 식별자를 사용했는지 확인하세요.
PermissionDeniedError	원인: 요청한 리소스에 접근할 권한이 없습니다. 해결 방법: 올바른 API 키, 조직 ID, 리소스 ID를 사용했는지 확인하세요.
RateLimitError	원인: 할당된 요청 한도에 도달했거나 트래픽을 너무 빠르게 늘렸습니다. 해결 방법: 요청 간격을 조절하세요. `Retry-After` 헤더가 있으면 설정한 재시도 한도 내에서 헤더가 지정한 대기 시간을 따르세요. 자세한 내용은 요청 한도 가이드를 참고하세요.
UnprocessableEntityError	원인: 요청 형식은 올바르지만 요청을 처리할 수 없습니다. 해결 방법: 요청을 다시 보내세요.

오류가 계속 발생하는 경우

문제가 계속되면 채팅으로 지원팀에 문의하고 다음 정보를 제공하세요.

사용 중이던 모델
수신한 오류 메시지와 코드
전송한 요청 데이터와 헤더
요청을 보낸 시각과 시간대
문제 진단에 도움이 될 만한 기타 정보

지원팀에서 문제를 조사한 뒤 최대한 빨리 답변드리겠습니다. 문의가 많으면 답변까지 시간이 걸릴 수 있습니다. 커뮤니티 포럼에 글을 올릴 수도 있습니다. 이때 민감한 정보는 제외하세요.

오류 처리

API가 반환하는 오류는 코드에서 처리하는 것이 좋습니다. 아래 예시를 참고하세요.

JavaScript

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21import OpenAI from "openai";

const client = new OpenAI();

try {
  const response = await client.responses.create({
    model: "gpt-6-astra",
    input: "Hello world",
  });
  console.log(response.output_text);
} catch (error) {
  if (error instanceof OpenAI.APIConnectionError) {
    console.error("Failed to connect to the OpenAI API:", error.message);
  } else if (error instanceof OpenAI.RateLimitError) {
    console.error("OpenAI API request exceeded its rate limit:", error.message);
  } else if (error instanceof OpenAI.APIError) {
    console.error("OpenAI API returned an error:", error.status, error.message);
  } else {
    throw error;
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15import openai
from openai import OpenAI

client = OpenAI()

try:
    response = client.responses.create(model="gpt-6-astra", input="Hello world")
except openai.APIConnectionError as e:
    print(f"Failed to connect to OpenAI API: {e}")
except openai.RateLimitError as e:
    print(f"OpenAI API request exceeded rate limit: {e}")
except openai.APIError as e:
    print(f"OpenAI API returned an API Error: {e}")
else:
    print(response.output_text)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28package main

import (
	"context"
	"errors"
	"fmt"

	"github.com/openai/openai-go/v3"
	"github.com/openai/openai-go/v3/responses"
)

func main() {
	client := openai.NewClient()
	response, err := client.Responses.New(context.Background(), responses.ResponseNewParams{
		Model: "gpt-6-astra",
		Input: responses.ResponseNewParamsInputUnion{OfString: openai.String("Hello world")},
	})
	if err != nil {
		var apiError *openai.Error
		if errors.As(err, &apiError) {
			fmt.Println("OpenAI API returned an API error:", apiError)
			return
		}
		fmt.Println("Failed to connect to OpenAI API:", err)
		return
	}
	fmt.Println(response.OutputText())
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.errors.OpenAIServiceException;
import com.openai.models.responses.ResponseCreateParams;

try {
  var response =
      client
          .responses()
          .create(
              ResponseCreateParams.builder().model("gpt-6-astra").input("Say hello.").build());

  response.output().stream()
      .flatMap(item -> item.message().stream())
      .flatMap(message -> message.content().stream())
      .flatMap(content -> content.outputText().stream())
      .forEach(text -> System.out.println(text.text()));
} catch (OpenAIServiceException error) {
  System.err.println(error.getMessage());
}

1
2
3
4
5
6
7
8
9require "openai"

client = OpenAI::Client.new
begin
  response = client.responses.create(model: "gpt-6-astra", input: "Say hello.")
  puts(response.output_text)
rescue OpenAI::Errors::APIError => error
  warn(error.message)
end

추천

시작하기

핵심 개념

SDK 및 CLI

클라우드 제공업체

자료

레거시 API

모델 선택하기

텍스트 및 코드

프롬프트 작성

추론

이미지

실시간 처리 및 오디오

특화 모델

Agents API

Agents SDK

ChatKit

검색 및 정보 조회

도구와 데이터 연결하기

도구를 활용한 워크플로우 구축하기

컴퓨터 및 코드

미디어

GPT-Live

Realtime API

음성 기능 개발

연결

오디오 처리

서비스 출시하기

성능 및 품질

평가

비용 및 처리량

안전 및 거버넌스

인프라 및 접근 권한

운영

핵심 개념

기획

개발

테스트 및 게시

전환 명세

가이드

자료

사용자 식별

ChatGPT 요금제 사용량

가이드

파일 업로드

API

성과 측정

광고주 API

API 레퍼런스

시작하기

시작하기

기초

둘러보기

지원 플랫폼

릴리스

워크플로우

주요 기능

Sites

dot

ChatGPT 스페이스

레퍼런스

맞춤 설정

설정 파일

에이전트 설정

ChatGPT와 Codex 확장하기

Linux

Windows

개발 워크플로우

확장 및 자동화

환경

Codex Cloud

Codex로 개발하기

서드 파티 통합

레퍼런스

권한

Codex Security

사이버 안전

시작하기

기능 설정

ID 및 액세스