JSON Schema 정보 추출 중 OpenAI API 오류 진단하기
구조화된 정보 추출 파이프라인에서 발생하는 OpenAI 인증 오류, 요청 제한, 시간 초과, 잘못된 JSON 문제를 해결하는 실용적인 절차를 소개합니다.
요약 · TL;DR
구조화된 정보 추출에 실패하면 전송 및 API 오류와 출력 검증 실패를 구분하세요. 먼저 인증 정보와 프로젝트 접근 권한을 확인하고, 일시적인 오류에만 재시도한 다음 반환된 JSON을 사용하기 전에 스키마에 맞는지 검증하세요.
핵심 요점
- 401 오류는 출력 스키마 문제가 아니라 인증 정보, 조직 멤버십 또는 IP 허용 목록과 관련된 문제입니다.
- 429 응답에서는 오류 코드를 확인하세요. 요청 제한에는 간격을 둔 재시도가 필요할 수 있지만, 크레딧 소진이나 지출 한도 초과에는 계정 설정 변경이 필요합니다.
- API 응답이 성공해도 추출 결과를 사용할 수 없을 수 있습니다. JSON을 파싱하고 JSON Schema에 맞는지 검증하세요.
- 재시도 횟수를 제한하고, 비밀 정보나 민감한 원문을 로그에 남기지 않으면서 반복 오류를 진단할 수 있도록 요청 메타데이터를 충분히 보존하세요.
목차 (7)
API 오류와 정보 추출 오류부터 구분하세요
구조화된 정보 추출 파이프라인에는 두 가지 별개의 실패 지점이 있습니다. 모델이 사용 가능한 응답을 반환하기 전에 요청이 실패할 수 있고, 응답을 받았더라도 파싱이나 스키마 검증 단계에서 실패할 수 있습니다. 이 두 문제를 구분해 처리하세요. 스키마나 응답을 살펴보지 않은 채 잘못된 출력을 재시도하면 요청을 낭비할 수 있으며, 크레딧이 소진된 상태에서 반복 재시도해도 접근 권한은 복구되지 않습니다.
OpenAI 오류 코드 가이드에는 API 상태 코드와 이에 대응하는 Python 라이브러리 예외 유형이 설명되어 있습니다. 정보 추출 작업에서는 다음과 같은 구분이 특히 유용합니다. 인증 및 요청 오류는 설정을 수정해야 하고, 일시적인 요청 제한이나 서비스 오류에는 횟수를 제한해 재시도할 수 있으며, 스키마 검증은 응답을 받은 뒤 애플리케이션에서 수행해야 합니다. OpenAI API 오류 코드
정보 추출 코드를 바꾸기 전에 인증을 확인하세요
401 오류가 발생하면 애플리케이션이 의도한 활성 API 키와 올바른 조직 컨텍스트를 사용하고 있는지 확인하세요. 오류 가이드에서는 조직 멤버십과 IP 허용 목록도 가능한 원인으로 안내합니다. 한 환경에서는 요청이 성공하지만 다른 환경에서는 실패한다면, 정보 추출 프롬프트를 수정하기 전에 환경별 외부 IP와 사용 가능한 인증 정보를 비교하세요.
403 오류가 발생하면 요청이 지원되는 국가, 지역 또는 영토에서 전송되는지 확인하세요. 권한이나 접근 제한은 JSON Schema 필드를 바꿔도 해결되지 않습니다.
인증 정보를 소스 코드 저장소나 로그에 남기지 마세요. 디버깅할 때는 비밀 키 자체가 아니라 환경 이름과 일부를 가린 키 식별자를 기록하세요.
재시도 전에 429 응답을 분류하세요
429가 항상 “잠시 후 같은 요청을 다시 보내라”는 뜻은 아닙니다. 오류 코드와 메시지를 확인하세요.
- 요청 속도 제한: 동시 요청 수를 줄이거나 요청 간격을 조정하세요.
Retry-After가 있으면 이를 따르고, 이전 요청 속도로 즉시 되돌리기보다 트래픽을 점진적으로 늘리세요. - 크레딧 잔액 소진: 요청을 재개하기 전에 크레딧을 추가하세요.
- 조직 또는 프로젝트 지출 한도: 해당 지출 한도를 검토하세요.
- 조직 사용량 한도: 승인된 한도의 상향을 요청하거나 지원팀에 문의하세요.
가이드에 따르면 이러한 결제 또는 사용량 한도 오류는 재시도만으로 복구되지 않습니다. 광범위한 오류 유형만 보지 말고 구체적인 오류 코드를 기준으로 처리 로직을 구성하세요. 일부 결제 오류는 다른 오류와 넓은 의미의 할당량 관련 유형을 공유할 수 있습니다.
정보 추출 배치에서는 모든 문서를 한꺼번에 실행하는 것보다 간단한 동시성 제한을 두는 편이 안전할 때가 많습니다. 일시적일 가능성이 있는 요청만 최대 시도 횟수와 백오프를 적용해 재시도하세요. 검증 실패를 요청 제한 오류처럼 재시도하지 마세요.
시간 초과와 일시적인 서비스 오류를 안전하게 처리하세요
클라이언트 시간 초과는 정해진 시간 안에 응답을 받지 못했다는 뜻이지, 요청이 처리되지 않았다는 증거는 아닙니다. 정보 추출 작업에서는 원본 문서마다 고유한 작업 ID를 부여하고 결과 저장을 멱등하게 처리하세요. 재시도할 경우 다운스트림에 레코드가 중복 생성되지 않도록 해야 합니다.
OpenAI 가이드는 500 서버 오류와 503 모델 과부하의 경우 잠시 기다린 뒤 재시도하면 도움이 될 수 있다고 안내하며, Retry-After가 있으면 이를 따르도록 합니다. 또한 APITimeoutError, InternalServerError, RateLimitError와 같은 Python 라이브러리 예외도 소개합니다. 반면 연결 실패는 네트워크, 프록시, 인증서 또는 방화벽 설정 문제일 수 있습니다. 이 모든 상황에 똑같은 재시도 정책을 적용해서는 안 됩니다.
Python 예시: 파싱하고 검증한 뒤 사용하기
아래 예시는 구조화된 응답을 처리할 때 필요한 검사를 보여주는 참고용 패턴입니다. 테스트를 거친 설정은 아닙니다. 사용 중인 모델, SDK 버전, 엔드포인트 및 구조화 출력 매개변수가 해당 요청 형식을 지원하는지 확인하세요. OpenAI 오류 코드 가이드에는 JSON Schema 매개변수의 호환성이 설명되어 있지 않습니다.
import json
from jsonschema import validate, ValidationError
from openai import OpenAI, APIConnectionError, APITimeoutError
from openai import APIStatusError, RateLimitError
client = OpenAI()
schema = {
"type": "object",
"properties": {
"invoice_number": {"type": "string"},
"total": {"type": "number"},
"currency": {"type": "string"}
},
"required": ["invoice_number", "total", "currency"],
"additionalProperties": False
}
try:
response = client.responses.create(
model="YOUR_SUPPORTED_MODEL",
input="Extract the invoice number, total, and currency from: ...",
text={
"format": {
"type": "json_schema",
"name": "invoice",
"strict": True,
"schema": schema
}
}
)
data = json.loads(response.output_text)
validate(instance=data, schema=schema)
except (RateLimitError, APITimeoutError, APIConnectionError) as exc:
# Apply a bounded, error-aware retry policy in the job runner.
print(f"Transient or connection failure: {exc}")
except APIStatusError as exc:
# Inspect status and the API error code before deciding what to do.
print(f"API failure: status={exc.status_code}, message={exc}")
except (json.JSONDecodeError, ValidationError) as exc:
# Quarantine the result; do not pass invalid data downstream.
print(f"Response failed JSON parsing or schema validation: {exc}")
선택한 엔드포인트나 모델이 이 스키마 형식 매개변수를 지원하지 않으면 요청이 잘못된 형식이거나 지원되지 않는 요청으로 처리되어 실패할 수 있습니다. 검증을 임의로 제거하지 말고 해당 엔드포인트의 최신 문서를 확인하세요. 제약된 출력 기능을 사용할 수 있더라도, 데이터가 데이터베이스나 업무 프로세스로 전달되기 전에 애플리케이션에서 파싱하고 검증하면 유용한 안전 경계가 마련됩니다.
간단한 진단 체크리스트
- 응답이 없거나 클라이언트 예외가 발생했나요? 연결 상태, 시간 초과 설정, 프록시 및 TLS 구성을 확인하세요.
- 401 또는 403 오류인가요? 키, 조직 접근 권한, IP 허용 목록 및 지역별 이용 가능 여부를 확인하세요.
- 429 오류인가요? 정확한 오류 코드를 확인하세요. 일시적인 요청 제한 오류에는 간격을 두고 재시도하고, 계정 제한에는 크레딧이나 한도를 조정하세요.
- 500 또는 503 오류인가요? 제한된 정책에 따라 재시도하고,
Retry-After가 있으면 따르세요. - 응답은 받았지만 사용할 수 없나요? 응답을 안전하게 기록하고 JSON 파싱과 스키마 검증 중 어느 단계에서 실패했는지 확인한 뒤, 유효하지 않은 레코드가 다운스트림 처리로 넘어가지 않게 하세요.
- 문제가 계속되나요? 모델 이름, 오류 코드와 메시지, 시간대가 포함된 타임스탬프, 관련 요청 정보와 헤더를 보존하세요. 진단 정보를 공유하기 전에 API 키와 민감한 원문을 가리세요.
결론
안정적인 JSON 정보 추출을 위해 먼저 HTTP 또는 SDK 오류를 진단하고, 성공적으로 받은 응답은 별도로 검증하세요. 복구 가능성이 있는 오류에만 재시도하고, 구체적인 오류 코드를 기준으로 요청 제한과 크레딧, 지출 한도 및 기타 접근 제약을 구분하세요.
FAQ
OpenAI 429 응답은 모두 재시도해야 하나요?
아니요. 요청 속도 제한 오류는 `Retry-After`가 있으면 이를 따르고, 정해진 한도 내에서 요청 속도를 조절해 재시도하세요. 크레딧 소진, 지출 한도 및 사용량 한도 오류는 관련 계정이나 한도를 변경해야 하며, 재시도만으로는 접근 권한이 복구되지 않습니다.
정보 추출 중 OpenAI 401 오류가 발생하면 무엇을 확인해야 하나요?
API 키가 올바르고 활성 상태인지, 요청이 의도한 조직을 사용하고 있는지, 계정이 해당 조직에 속해 있는지 확인하세요. IP 허용 목록을 설정했다면 요청이 승인된 IP에서 시작되는지도 확인하세요.
API 응답이 성공하면 스키마에 맞는 JSON도 보장되나요?
아니요. 반환된 텍스트를 파싱하고, 결과 객체를 사용하기 전에 애플리케이션의 JSON Schema에 맞는지 검증하세요. 또한 선택한 엔드포인트, 모델 및 SDK가 요청에 사용한 구조화 출력 매개변수를 지원하는지 확인하세요.
오류가 계속될 때 어떤 정보를 보존해야 하나요?
모델, 오류 코드와 메시지, 시간대가 포함된 타임스탬프, 관련 요청 정보와 헤더를 기록하세요. 진단 정보를 로그에 남기거나 공유하기 전에 인증 정보와 민감한 입력은 가리세요.
관련 글
Guides
JSON 추출 워크플로를 위한 Grok Imagine Image API 비용 추정
Grok Imagine Image의 이미지 생성 비용을 추정하고, 확인되지 않은 추출 비용을 파악하며, 구조화된 레코드를 JSON 스키마로 검증하는 방법을 알아봅니다.
Guides
구조화 추출을 위한 GPT 6.2 Sol API 비용: 재현 가능한 추정
토큰, 재시도, 캐시 및 컨텍스트 구간에 관한 명시적 가정을 바탕으로 GPT 6.2 Sol 구조화 추출 비용을 추정합니다.
Guides
구조화 추출을 위한 GPT Image 2.6 Sunburst API 비용 계획 가이드
토큰 사용량 가정, 스키마 검증, 재시도와 가격 정보의 한계를 고려해 이미지-JSON 작업 비용을 추정합니다.
Guides
스키마 검증 추출을 위한 GPT Image 2.6 Flare API 비용 추정
문서화된 이미지 토큰 요금과 확인되지 않은 추출 및 OneMux 가격을 구분하여 재현 가능한 API 예산을 세우는 방법을 알아봅니다.