Skip to Content
개발 문서가이드오류 처리

오류 처리

이 가이드에서는 OfoxAI API의 오류 응답 형식, 일반적인 오류 시나리오 및 권장 처리 전략을 소개합니다.

오류 응답 형식

모든 오류 응답은 통일된 JSON 형식을 따릅니다:

{
  "error": {
    "code": "invalid_api_key",
    "message": "제공된 API Key가 유효하지 않습니다. 확인 후 다시 시도하세요.",
    "type": "authentication_error"
  }
}

HTTP 상태 코드

상태 코드타입설명재시도 여부
400invalid_request_error요청 파라미터 오류❌ 파라미터 수정 후 재시도
401authentication_errorAPI Key 유효하지 않거나 누락됨❌ API Key 확인
403permission_error권한 부족❌ 계정 권한 확인
404not_found_error모델 또는 리소스가 존재하지 않음❌ 모델 ID 확인
429rate_limit_error속도 제한 초과✅ 대기 후 재시도
500internal_error서버 내부 오류✅ 잠시 후 재시도
502upstream_error상위 모델 공급자 오류✅ 모델 변경 또는 재시도
503service_unavailable서비스 일시 중단✅ 잠시 후 재시도

일반적인 오류 및 해결 방법

401 — API Key 유효하지 않음

{"error": {"code": "invalid_api_key", "message": "The API key provided is invalid."}}

해결 방법:

  • API Key가 올바르게 복사되었는지 확인 (sk- 접두사 포함)
  • Key가 만료되거나 비활성화되지 않았는지 확인
  • 환경 변수가 올바르게 로드되었는지 확인

429 — 속도 제한

{"error": {"code": "rate_limit_exceeded", "message": "Rate limit reached. Please retry after 1s."}}

해결 방법:

  • 응답 헤더의 x-ratelimit-reset-requests 확인
  • 지수 백오프 재시도 구현
  • 더 높은 할당량이 필요하면 지원팀에 조정 요청

502 — 업스트림 오류

{"error": {"code": "upstream_error", "message": "The upstream provider returned an error."}}

해결 방법:

  • 장애 복구를 사용하여 자동으로 대체 모델로 전환
  • 잠시 후 재시도
  • 모델 공급자 상태 페이지 확인

재시도 전략

지수 백오프 (Exponential Backoff) 전략 사용을 권장합니다:

retry.py
import time
import random
from openai import OpenAI, APIError, RateLimitError, APIConnectionError
 
client = OpenAI(
    base_url="https://api.ofox.ai/v1",
    api_key="<OFOXAI_API_KEY>"
)
 
def chat_with_retry(max_retries=5, **kwargs):
    """지수 백오프가 포함된 재시도 래퍼"""
    for attempt in range(max_retries):
        try:
            return client.chat.completions.create(**kwargs)
 
        except RateLimitError:
            # 429: 대기 후 재시도
            wait = (2 ** attempt) + random.uniform(0, 1)
            print(f"속도 제한 초과, {wait:.1f}초 대기 후 재시도...")
            time.sleep(wait)
 
        except APIConnectionError:
            # 네트워크 오류: 잠시 대기 후 재시도
            wait = 2 ** attempt
            print(f"연결 오류, {wait}초 대기 후 재시도...")
            time.sleep(wait)
 
        except APIError as e:
            if e.status_code and e.status_code >= 500:
                # 5xx: 서버 오류, 재시도
                wait = 2 ** attempt
                time.sleep(wait)
            else:
                # 4xx: 클라이언트 오류, 재시도하지 않음
                raise
 
    raise Exception(f"{max_retries}회 재시도 후에도 실패")
 
# 사용 예시
response = chat_with_retry(
    model="openai/gpt-4o",
    messages=[{"role": "user", "content": "안녕하세요"}]
)

타임아웃 설정

API 호출에 적절한 타임아웃을 설정하는 것을 권장합니다:

# Python OpenAI SDK
client = OpenAI(
    base_url="https://api.ofox.ai/v1",
    api_key="<OFOXAI_API_KEY>",
    timeout=60.0,  # 60초 타임아웃
    max_retries=3  # SDK 내장 재시도
)
// TypeScript OpenAI SDK
const client = new OpenAI({
  baseURL: 'https://api.ofox.ai/v1',
  apiKey: '<OFOXAI_API_KEY>',
  timeout: 60000,  // 60초 타임아웃
  maxRetries: 3    // SDK 내장 재시도
})

스트리밍 요청에는 더 긴 타임아웃(120-300초)을 사용하는 것이 좋습니다. 모델이 전체 콘텐츠를 생성하는 데 시간이 더 오래 걸릴 수 있기 때문입니다.

모범 사례

  1. 재시도 가능한 오류와 불가능한 오류 구분 — 4xx는 일반적으로 요청 수정이 필요하고, 5xx는 재시도 가능
  2. 지수 백오프 사용 — 속도 제한 시 빈번한 재시도 방지
  3. 최대 재시도 횟수 설정 — 무한 재시도 방지
  4. 오류 로그 기록 — 문제 해결에 유용
  5. 장애 복구 설정 — OfoxAI의 provider.fallback 파라미터로 자동 모델 전환
  6. 오류율 모니터링 — 콘솔에서 오류 추세 확인
Last updated on
구조화된 출력공급자 라우팅