메인 콘텐츠로 건너뛰기

​
오류 응답 형식

모든 오류는 선택적인 Agent-First 힌트와 함께 일관된 JSON 형식으로 반환됩니다: 
{
  "error": {
    "message": "Human-readable error description",
    "type": "error_type",
    "code": "error_code",
    "param": "parameter_name",
    "did_you_mean": "suggested_model",
    "suggestions": [{"id": "model-id"}],
    "hint": "Next step guidance",
    "retryable": true,
    "retry_after": 30
  }
}
기본 필드 (message, type, code, param)는 항상 존재합니다. 힌트 필드 (did_you_mean, suggestions, hint, retryable, retry_after, balance_usd, estimated_cost_usd)는 AI 에이전트의 자체 수정(self-correction)을 위한 선택적 확장입니다. 자세한 내용은 Agent-First API 가이드를 참조하세요. OpenAI-compatible endpoints는 LemonData의 안정적인 게이트웨이 오류 유형을 사용합니다. Anthropic-compatible 및 Gemini-compatible endpoints는 자체 네이티브 오류 계열 및 응답 형태를 사용합니다.

​
HTTP 상태 코드

코드설명
400잘못된 요청 - 잘못된 파라미터
401인증 실패 - 유효하지 않거나 누락된 API 키
402결제 필요 - 잔액 부족
403접근 금지 - 접근 거부 또는 모델 사용 불가
404찾을 수 없음 - 모델 또는 리소스가 없음
413요청 본문이 너무 큼 - 입력 또는 파일 크기 초과
429요청 과다 - 속도 제한 초과
500서버 내부 오류
502잘못된 게이트웨이 - 업스트림 제공자 오류
503서비스 사용 불가 - 서비스 일시적 사용 불가
504게이트웨이 타임아웃 - 요청 시간 초과

​
오류 유형

​
인증 오류 (401)

유형코드설명
invalid_api_keyinvalid_api_keyAPI 키가 누락되었거나 유효하지 않음
expired_api_keyexpired_api_keyAPI 키가 폐기되었음
from openai import OpenAI, AuthenticationError

try:
    response = client.chat.completions.create(...)
except AuthenticationError as e:
    print(f"Authentication failed: {e.message}")

​
결제 오류 (402)

유형코드설명
insufficient_balanceinsufficient_balance계정 잔액이 부족함 (OpenAI-compatible endpoints)
insufficient_balance_errorinsufficient_balance계정 잔액이 부족함 (Anthropic-compatible endpoints)
quota_exceededquota_exceededAPI 키 사용 한도 초과
from openai import OpenAI, APIStatusError

try:
    response = client.chat.completions.create(...)
except APIStatusError as e:
    if e.status_code == 402:
        print("Please top up your account balance")

​
접근 오류 (403)

유형코드설명
access_deniedaccess_denied리소스 접근 거부
access_deniedmodel_not_allowed이 API 키로 해당 모델을 사용할 수 없음
{
  "error": {
    "message": "You don't have permission to access this model",
    "type": "access_denied",
    "code": "model_not_allowed"
  }
}

​
유효성 검사 오류 (400)

유형설명
invalid_request_error요청 파라미터가 유효하지 않음
context_length_exceeded모델에 대한 입력 길이가 너무 김
model_not_found요청한 모델이 현재 공개 계약에서 사용 불가
{
  "error": {
    "message": "Model not found: please check the model name",
    "type": "invalid_request_error",
    "param": "model",
    "code": "model_not_found",
    "did_you_mean": "gpt-5.4",
    "suggestions": [{"id": "gpt-5.4"}, {"id": "gpt-5-mini"}],
    "hint": "Did you mean 'gpt-5.4'? Use GET https://api.lemondata.cc/v1/models to list all available models."
  }
}
공개 라우트는 응답 본문에서 오타, 비공개(hidden), 보류(deferred), 비공개 상태를 구분하지 않습니다. 모델이 현재 공개 계약을 통해 사용 불가능한 경우, LemonData는 model_not_found를 반환합니다.

​
속도 제한 오류 (429)

요금 제한을 초과하면: 
{
  "error": {
    "message": "Rate limit: 60 rpm exceeded",
    "type": "rate_limit_exceeded",
    "code": "rate_limit_exceeded",
    "retryable": true,
    "retry_after": 8,
    "hint": "Rate limited. Retry after 8s. Current limit: 60/min for user role."
  }
}
포함된 헤더: 
Retry-After: 8
Retry-After 헤더와 retry_after 필드는 모두 재시도 전 대기해야 할 정확한 초(seconds)를 나타냅니다.

​
페이로드가 너무 큼 (413)

입력 또는 파일 크기가 제한을 초과하면: 
{
  "error": {
    "message": "Input size exceeds maximum allowed",
    "type": "invalid_request_error",
    "code": "payload_too_large"
  }
}
일반적인 원인:
  • 이미지 파일이 너무 큼 (최대 20MB)
  • 오디오 파일이 너무 큼 (최대 25MB)
  • 입력 텍스트가 모델의 컨텍스트 길이를 초과함

​
업스트림 오류 (502, 503)

유형설명
upstream_error제공자가 오류를 반환함
all_channels_failed사용 가능한 제공자가 없음
timeout_error요청이 시간 초과됨
모든 채널이 실패하면 응답에 대체 모델이 포함됩니다: 
{
  "error": {
    "message": "Model claude-opus-4-6 temporarily unavailable",
    "code": "all_channels_failed",
    "retryable": true,
    "retry_after": 30,
    "alternatives": [
      {"id": "claude-sonnet-4-6", "status": "available", "tags": []},
      {"id": "gpt-5-mini", "status": "available", "tags": []}
    ],
    "hint": "Retry in 30s or switch to an available model."
  }
}

​
Python에서 오류 처리

from openai import OpenAI, APIError, RateLimitError, APIConnectionError

client = OpenAI(
    api_key="sk-your-api-key",
    base_url="https://api.lemondata.cc/v1"
)

def chat_with_retry(messages, max_retries=3):
    for attempt in range(max_retries):
        try:
            return client.chat.completions.create(
                model="gpt-4o",
                messages=messages
            )
        except RateLimitError as e:
            if attempt < max_retries - 1:
                import time
                time.sleep(2 ** attempt)  # Exponential backoff
                continue
            raise
        except APIConnectionError as e:
            print(f"Connection error: {e}")
            raise
        except APIError as e:
            print(f"API error: {e.status_code} - {e.message}")
            raise

​
JavaScript에서 오류 처리

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: 'sk-your-api-key',
  baseURL: 'https://api.lemondata.cc/v1'
});

async function chatWithRetry(messages, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await client.chat.completions.create({
        model: 'gpt-4o',
        messages
      });
    } catch (error) {
      if (error instanceof OpenAI.RateLimitError) {
        if (attempt < maxRetries - 1) {
          await new Promise(r => setTimeout(r, 2 ** attempt * 1000));
          continue;
        }
      }
      throw error;
    }
  }
}

​
모범 사례

속도 제한에 걸렸을 때 재시도 사이에 점점 더 긴 대기 시간을 둡니다:
wait_time = 2 ** attempt  # 1s, 2s, 4s, 8s...
요청이 중단되는 것을 방지하려면 항상 적절한 타임아웃을 설정하세요:
client = OpenAI(timeout=60.0)  # 60 second timeout
지원 요청을 위해 요청 ID를 포함한 전체 오류 응답을 로깅하세요:
except APIError as e:
    logger.error(f"API Error: {e.status_code} - {e.message}")
일부 모델은 특정 요구사항(예: 최대 토큰 수, 이미지 형식)을 가집니다. 요청을 하기 전에 입력을 검증하세요.