> For the complete documentation index, see [llms.txt](https://runyourai.gitbook.io/userguide/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://runyourai.gitbook.io/userguide/api/errorguide.md).

# 오류 해결하기

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로 확인하세요.