에러 처리

API 요청이 실패하면 HTTP 상태 코드와 함께 JSON 형식의 에러 응답이 반환됩니다.

에러 응답 형식

{
  "error": {
    "code": "invalid_api_key",
    "message": "Invalid API key provided.",
    "type": "authentication_error",
    "status": 401
  }
}

HTTP 상태 코드

코드	의미	대처 방법
400	잘못된 요청	요청 파라미터 확인. 필수 필드 누락 또는 타입 오류
401	인증 실패	API Key 확인. 콘솔에서 재발급
403	권한 없음	모델 접근 권한 또는 플랜 확인
404	리소스 없음	엔드포인트 URL 또는 모델 ID 확인
429	요청 한도 초과	잠시 후 재시도. 지수 백오프 전략 권장
500	서버 오류	iwinv 서버 오류. 지속 시 기술지원 신청
503	서비스 일시 불가	모델 서버 과부하. 잠시 후 재시도

재시도 전략 (지수 백오프)

Python

import openai
import time

def chat_with_retry(client, model, messages, max_retries=3):
    for attempt in range(max_retries):
        try:
            return client.chat.completions.create(
                model=model,
                messages=messages
            )
        except openai.AuthenticationError:
            # 401 — Key 오류, 재시도해도 소용없음
            raise
        except openai.RateLimitError:
            # 429 — 잠시 후 재시도
            wait = 2 ** attempt
            print(f"Rate limit. {wait}초 후 재시도...")
            time.sleep(wait)
        except openai.APIStatusError:
            # 500, 503 — 서버 오류
            if attempt == max_retries - 1:
                raise
            time.sleep(2 ** attempt)
    raise Exception("최대 재시도 횟수 초과")

# 사용 예시
response = chat_with_retry(
    client,
    model="gemma4-26b",
    messages=[{"role": "user", "content": "안녕!"}]
)

Node.js

async function chatWithRetry(client, model, messages, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await client.chat.completions.create({ model, messages });
    } catch (err) {
      // 401 — 재시도 불필요
      if (err.status === 401) throw err;

      if (err.status === 429 || err.status >= 500) {
        const wait = 2 ** attempt * 1000;
        console.log(`재시도 대기 ${wait}ms...`);
        await new Promise(r => setTimeout(r, wait));
      } else {
        throw err;
      }
    }
  }
  throw new Error("최대 재시도 횟수 초과");
}

경고

Key 인증 오류(401)는 재시도해도 해결되지 않습니다.
API Key가 유효한지, 만료되지 않았는지 먼저 확인하세요.

위험

Key가 정상 작동하지 않는 경우 iwinv 콘솔에서 Key 상태를 확인하거나,
온라인 기술지원을 신청하시기 바랍니다.