# 오류 해결하기

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

***

### 오류 응답 형식

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

```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)** 재시도 로직을 추가하세요.

{% tabs %}
{% tab title="Python" %}

```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
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
async function createWithRetry(params, maxAttempts = 5) {
  for (let attempt = 0; attempt < maxAttempts; attempt++) {
    try {
      return await client.chat.completions.create(params);
    } catch (e) {
      if (e?.status === 429 && attempt < maxAttempts - 1) {
        const wait = 2 ** attempt * 1000; // 1초, 2초, 4초, 8초...
        console.log(`${wait / 1000}초 후 재시도합니다...`);
        await new Promise((res) => setTimeout(res, wait));
      } else {
        throw e;
      }
    }
  }
}
```

{% endtab %}
{% endtabs %}

***

#### 5xx — 서버 오류

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

**해결 방법:**

* 잠시 후 다시 시도합니다.
* 오류가 지속된다면  고객지원으로 문의해주세요.

***

### 크레딧 부족 오류

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

**해결 방법:**

1. 콘솔 우측 상단에서 현재 크레딧 잔액을 확인합니다.
2. **크레딧 충전** 메뉴에서 크레딧을 충전 후 다시 시도합니다.

***

### 자주 묻는 질문

**Q. 요청을 보냈는데 응답이 오지 않아요.**&#x20;

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

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

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

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

`400` 오류가 반환됩니다. 현재 사용 가능한 모델 목록은 [모델 선택하기](https://app.gitbook.com/o/Z5CfKdTVzB2gxdCaBErO/s/hwfS5OO0ZQXTwDAwWcnj/~/edit/~/changes/418/api/undefined-1) 페이지 또는 `/v1/models` API로 확인하세요.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://runyourai.gitbook.io/userguide/api/errorguide.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.