오류 처리

모든 오류 응답은 통일된 구조를 따르며, 각 오류 코드에는 code + message + 권장 조치가 함께 제공되어 자동화 처리가 용이합니다.

재시도 황금 법칙

인증 오류(401)는 재시도하지 않고 그대로 상위로 전달하며, 속도 제한(429)은 2 ** attempt초의 지수 백오프 후 재시도하고, 그 외 API 오류는 max_retries 한도까지 재시도합니다.

오류 응답 형식

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

{ "error": { "code": "error_code", "message": "Human readable error message", "type": "error_type", "param": "optional_parameter_name" } }

HTTP 상태 코드

상태 코드	의미	설명
200	성공	요청이 성공적으로 처리됨
400	요청 오류	매개변수 오류 또는 형식이 올바르지 않음
401	인증 안 됨	API Key가 유효하지 않거나 누락됨
403	접근 금지	해당 리소스에 접근할 권한이 없음
404	찾을 수 없음	요청한 리소스가 존재하지 않음
429	요청 과다	속도 제한을 초과함
500	서버 오류	서버 내부 오류
502	게이트웨이 오류	업스트림 서비스를 사용할 수 없음
503	서비스 사용 불가	서비스를 일시적으로 사용할 수 없음

일반적인 오류

증상별 빠른 진단

"어떤 오류가 발생했는가"에서 출발하여 항목별 체크리스트를 보려면 문제 해결을 참고하세요. 이 페이지는 전체 오류 코드와 재시도 전략에 대한 권위 있는 참고 자료입니다.

code	type	message(예시)	해결 방법
invalid_api_key	authentication_error	Invalid API key provided	Key가 올바르게 복사되었는지, sk-로 시작하는지, 불필요한 공백이 없는지 확인하세요
model_not_found	new_api_error	모델 xxx 사용 가능한 채널 없음	모델 이름을 확인하고, 해당 모델에 채널이 구성되어 있는지 확인하며, 관리자에게 권한 활성화를 요청하세요
insufficient_quota	billing_error	Insufficient quota for this request	계정 잔액을 확인하고 관리자에게 충전을 요청하세요
rate_limit_exceeded	rate_limit_error	Rate limit exceeded. Please slow down.	요청 빈도를 줄이고, 지수 백오프로 재시도하며, 속도 제한 상향을 신청하세요
context_length_exceeded	invalid_request_error	This model’s maximum context length is 8192 tokens	입력 길이를 줄이고, 더 긴 컨텍스트 모델로 전환하며, 슬라이딩 윈도우로 히스토리를 자르세요

model_not_found 응답 본문(HTTP 404, type: new_api_error):

{
  "error": {
    "code": "model_not_found",
    "message": "模型 gpt-5 无可用渠道",
    "type": "new_api_error"
  }
}

insufficient_quota 응답 본문(HTTP 402, type: billing_error):

{
  "error": {
    "code": "insufficient_quota",
    "message": "Insufficient quota for this request",
    "type": "billing_error"
  }
}

오류 처리 모범 사례

핵심: 인증 오류(401)는 재시도하지 않고 그대로 상위로 전달하고, 속도 제한(429)은 지수 백오프(2 ** attempt초) 후 재시도하며, 그 외 API 오류는 max_retries 한도까지 재시도합니다.

from openai import OpenAI, APIError, RateLimitError, AuthenticationError
import time

client = OpenAI(base_url="https://hub.lurus.cn/v1", api_key="sk-your-api-key")

def chat_with_retry(messages, max_retries=3):
    for attempt in range(max_retries):
        try:
            return client.chat.completions.create(model="deepseek-chat", messages=messages)
        except AuthenticationError as e:
            print(f"Authentication failed: {e}")  # Key 问题，不重试
            raise
        except RateLimitError:
            wait_time = 2 ** attempt
            print(f"Rate limited. Waiting {wait_time}s...")
            time.sleep(wait_time)
        except APIError as e:
            if attempt == max_retries - 1:
                raise
            print(f"API error: {e}. Retrying...")
            time.sleep(1)
    raise Exception("Max retries exceeded")

import OpenAI from 'openai';

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

async function chatWithRetry(messages, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await client.chat.completions.create({ model: 'deepseek-chat', messages });
    } catch (error) {
      if (error.status === 401) throw error;  // 认证错误，不重试
      if (error.status === 429) {
        const wait = Math.pow(2, attempt) * 1000;
        console.log(`Rate limited. Waiting ${wait}ms...`);
        await new Promise(r => setTimeout(r, wait));
        continue;
      }
      if (attempt === maxRetries - 1) throw error;
      console.log(`Error: ${error.message}. Retrying...`);
      await new Promise(r => setTimeout(r, 1000));
    }
  }
}

지원 문의

문제가 계속되나요? support@lurus.cn으로 문의하세요

빠른 진단을 위해 다음 정보를 제공해 주세요:

• 오류 메시지 전체 내용
• 요청 ID(response header X-Request-ID)
• 발생 시각
• 재현 단계

---

다음 단계

Chat Completions API인증API 개요