> ## Documentation Index
> Fetch the complete documentation index at: https://docs.adrop.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 에러 코드

> REST API 에러 코드와 해결 방법을 안내합니다.

## 에러 코드 목록

| 코드     | 상수                           | 메시지            | 설명               |
| ------ | ---------------------------- | -------------- | ---------------- |
| `0`    | OK                           | OK             | 성공               |
| `4000` | ERROR\_CODE\_INVALID\_UNIT   | Invalid unit   | 유효하지 않은 광고 유닛 ID |
| `4001` | ERROR\_CODE\_AD\_INACTIVE    | Ad inactive    | 활성화된 광고 캠페인 없음   |
| `4002` | ERROR\_CODE\_AD\_NO\_FILL    | No fill        | 기준에 맞는 광고 없음     |
| `4003` | ERROR\_CODE\_INVALID\_PARAMS | Invalid params | 유효하지 않은 파라미터     |

***

## 에러별 상세 설명

### ERROR\_CODE\_INVALID\_UNIT (4000)

**원인**: 존재하지 않거나 비활성화된 광고 유닛 ID로 요청했습니다.

**해결 방법**:

* 콘솔에서 광고 유닛 ID가 정확한지 확인
* 광고 유닛이 활성화 상태인지 확인
* 복사/붙여넣기 시 공백이나 특수문자가 포함되지 않았는지 확인

```json theme={null}
{
    "code": 4000,
    "msg": "Invalid unit",
    "result": null
}
```

***

### ERROR\_CODE\_AD\_INACTIVE (4001)

**원인**: 해당 광고 유닛에 활성화된 광고 캠페인이 없습니다.

**해결 방법**:

* 콘솔에서 캠페인이 실행 중인지 확인
* 캠페인 일정(시작일/종료일)을 확인
* 캠페인 예산이 소진되지 않았는지 확인

```json theme={null}
{
    "code": 4001,
    "msg": "Ad inactive",
    "result": null
}
```

***

### ERROR\_CODE\_AD\_NO\_FILL (4002)

**원인**: 타겟팅 조건에 맞는 광고를 찾을 수 없습니다.

**해결 방법**:

* 타겟팅 설정이 너무 제한적이지 않은지 확인
* 재시도 로직 구현 (지수 백오프 권장)
* 대체 콘텐츠(폴백) 준비

```json theme={null}
{
    "code": 4002,
    "msg": "No fill",
    "result": null
}
```

**재시도 구현 예시**:

```javascript theme={null}
async function requestAdWithRetry(params, maxRetries = 3) {
    for (let i = 0; i < maxRetries; i++) {
        try {
            const response = await axios.get('https://api-v2.adrop.io/request', {
                params,
                headers: { 'Authorization': 'YOUR_APP_KEY' }
            });

            if (response.data.code === 0) {
                return response.data.result;
            }

            if (response.data.code === 4002) {
                // No fill - 재시도
                await new Promise(r => setTimeout(r, Math.pow(2, i) * 1000));
                continue;
            }

            // 다른 에러는 즉시 반환
            throw new Error(response.data.msg);
        } catch (error) {
            if (i === maxRetries - 1) throw error;
        }
    }

    return null; // 폴백 콘텐츠 표시
}
```

***

### ERROR\_CODE\_INVALID\_PARAMS (4003)

**원인**: 요청 파라미터가 잘못되었습니다.

**해결 방법**:

* 필수 파라미터(`unit`)가 포함되었는지 확인
* 파라미터 값의 형식이 올바른지 확인
* 파라미터 이름에 오타가 없는지 확인

```json theme={null}
{
    "code": 4003,
    "msg": "Invalid params",
    "result": null
}
```

**파라미터 체크리스트**:

| 파라미터    | 필수 | 올바른 값 예시                |
| ------- | -- | ----------------------- |
| `unit`  | 필수 | `AD_UNIT_123`           |
| `pf`    | 권장 | `android`, `ios`, `web` |
| `lcl`   | 권장 | `ko_KR`, `en_US`        |
| `theme` | 선택 | `light`, `dark`         |

***

## 에러 처리 모범 사례

### 1. 에러 코드 기반 분기 처리

```javascript theme={null}
function handleAdResponse(response) {
    switch (response.code) {
        case 0:
            // 성공 - 광고 렌더링
            renderAd(response.result);
            break;
        case 4000:
            // 유닛 ID 오류 - 로그 기록
            console.error('Invalid unit ID');
            break;
        case 4001:
        case 4002:
            // 광고 없음 - 폴백 콘텐츠 표시
            showFallbackContent();
            break;
        case 4003:
            // 파라미터 오류 - 개발자에게 알림
            console.error('Invalid parameters:', response.msg);
            break;
        default:
            // 알 수 없는 에러
            console.error('Unknown error:', response.code, response.msg);
    }
}
```

### 2. 폴백 콘텐츠 준비

```javascript theme={null}
function showFallbackContent() {
    const container = document.getElementById('ad-container');
    container.innerHTML = `
        <div class="fallback-content">
            <img src="/images/house-ad.jpg" alt="House Ad" />
        </div>
    `;
}
```

### 3. 모니터링 및 로깅

```javascript theme={null}
function logAdError(code, message, params) {
    // 에러 발생률 모니터링
    analytics.track('ad_error', {
        error_code: code,
        error_message: message,
        unit_id: params.unit,
        timestamp: new Date().toISOString()
    });
}
```

***

## HTTP 상태 코드

REST API는 표준 HTTP 상태 코드도 함께 반환합니다.

| HTTP 상태 | 설명                        |
| ------- | ------------------------- |
| `200`   | 요청 성공 (에러 코드는 응답 본문에서 확인) |
| `401`   | 인증 실패 (App Key 확인)        |
| `500`   | 서버 내부 오류                  |

<Warning>
  HTTP 200이라도 응답 본문의 `code` 값을 반드시 확인하세요. 비즈니스 로직 에러는 응답 본문에 포함됩니다.
</Warning>

***

## 관련 문서

<CardGroup cols={2}>
  <Card title="REST API 개요" icon="server" href="/ko/sdk/rest-api">
    API 기본 사용법
  </Card>

  <Card title="타겟팅 설정" icon="bullseye" href="/ko/sdk/rest-api/targeting">
    타겟팅 파라미터 설정
  </Card>
</CardGroup>