오류 해결하기

API 호출 중 오류가 발생했을 때 원인과 해결 방법을 안내합니다.

---

오류 응답 형식

오류가 발생하면 아래와 같은 JSON 형식으로 응답이 반환됩니다.

{
  "statusCode": 401,
  "timestamp": "2026-03-24T00:00:00.000Z",
  "path": "/v1/chat/completions",
  "message": "Invalid API key"
}

statusCode와 message를 확인하여 원인을 파악하세요.

---

오류 코드별 원인 및 해결 방법

401 — API 키 인증 실패

원인: API 키가 올바르지 않거나, 만료 또는 삭제된 키를 사용하고 있습니다.

해결 방법:

1. API 키 앞에 Bearer 접두사가 포함되어 있는지 확인합니다.

   Authorization: Bearer runyour-v1-YOUR_API_KEY   ← 올바른 형식
   Authorization: runyour-v1-YOUR_API_KEY           ← 잘못된 형식

2. 콘솔 > API 키 관리에서 해당 키가 활성 상태인지 확인합니다.

3. 키가 삭제되었다면 새 키를 발급하세요.

---

400 — 잘못된 요청

원인: 요청 형식이 잘못되었습니다. 주로 모델 ID 형식 오류, 필수 파라미터 누락, 지원되지 않는 조합 사용 시 발생합니다.

해결 방법:

• 모델 ID가 provider/model 형식인지 확인합니다.

  "model": "openai/gpt-5.2"   ← 올바른 형식
  "model": "gpt-5.2"           ← 잘못된 형식 (provider 누락)

• messages 배열이 비어있지 않은지 확인합니다.

• Responses API(/v1/responses)에서 openai/... 이외의 모델로 스트리밍을 시도한 경우, Chat Completions(/v1/chat/completions)으로 전환하세요.

---

429 — 요청 한도 초과

원인: 짧은 시간 안에 너무 많은 요청이 발생했습니다.

해결 방법:

• 잠시 기다린 후 다시 시도합니다.

• 코드에 지수 백오프(Exponential Backoff) 재시도 로직을 추가하세요.

Python

import time

for attempt in range(5):
    try:
        response = client.chat.completions.create(...)
        break
    except Exception as e:
        if "429" in str(e):
            wait = 2 ** attempt  # 1초, 2초, 4초, 8초...
            print(f"{wait}초 후 재시도합니다...")
            time.sleep(wait)
        else:
            raise

JavaScript

---

5xx — 서버 오류

원인: RunYour AI 서버 또는 AI 프로바이더(OpenAI, Anthropic 등) 측의 일시적인 오류입니다.

해결 방법:

• 잠시 후 다시 시도합니다.

• 오류가 지속된다면 고객지원으로 문의해주세요.

---

크레딧 부족 오류

원인: 잔여 크레딧이 부족하여 API 응답을 생성할 수 없습니다.

해결 방법:

1. 콘솔 우측 상단에서 현재 크레딧 잔액을 확인합니다.

2. 크레딧 충전 메뉴에서 크레딧을 충전 후 다시 시도합니다.

---

자주 묻는 질문

Q. 요청을 보냈는데 응답이 오지 않아요.

응답 시간은 선택한 모델과 요청 길이에 따라 다릅니다. 특히 추론 모델(o-series 등)은 응답 생성에 시간이 걸릴 수 있습니다. 스트리밍(stream: true)을 활성화하면 기다리는 시간 없이 결과를 바로 받아볼 수 있습니다.

Q. 같은 입력인데 응답이 매번 달라요.

temperature 값이 높을수록 응답이 다양하게 생성됩니다. 동일한 응답이 필요하다면 temperature: 0으로 설정하세요.

Q. 지원하지 않는 모델 ID를 입력하면 어떻게 되나요?

400 오류가 반환됩니다. 현재 사용 가능한 모델 목록은 모델 선택하기 페이지 또는 /v1/models API로 확인하세요.