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

# 에러 처리

> DARO Android SDK의 통합 에러 코드(DaroErrorCode)와 DaroError 객체로 광고 로드 실패를 일관되게 처리하는 방법을 안내합니다.

## 개요

DARO SDK는 광고 로드가 실패하면 통합 에러 객체 `DaroError`를 전달합니다. 모든 오류는 동일한 `DaroErrorCode` 체계로 변환되므로, 퍼블리셔는 하나의 분기 로직으로 에러를 처리할 수 있습니다.

***

## DaroError 객체

로드 실패 콜백은 `DaroError` 객체를 전달합니다. 주요 프로퍼티는 다음과 같습니다.

| 프로퍼티 | 타입 | 설명 |
| - | - | - |
| `errorCode` | `Int` | 통합 에러 코드의 정수 값입니다. |
| `errorCodeName` | `DaroErrorCode` | 통합 에러 코드의 이름(enum)입니다. 분기 처리에 사용하세요. |
| `errorMessage` | `String` | 오류 메시지입니다. 로깅·디버깅에 활용하세요. |
| `latency` | `Int` | 광고 요청에 소요된 시간(ms)입니다. |

***

## 통합 에러 코드

`DaroErrorCode`는 아래 코드로 구성됩니다. 분기 처리는 정수 값이 아닌 `errorCodeName`(enum)으로 하는 것을 권장합니다.

### 초기화·설정 오류

| 코드 | 이름 | 발생 조건 | 권장 대응 |
| - | - | - | - |
| `-1` | `UNSPECIFIED` | 분류되지 않은 일반 오류입니다. | `errorMessage`를 확인하고 잠시 후 다시 요청하세요. |
| `-2` | `NOT_INITIALIZED` | SDK가 초기화되지 않은 상태에서 광고를 요청했습니다. | SDK 초기화가 완료된 뒤 광고를 요청하세요. |
| `-3` | `INITIALIZATION_FAILED` | SDK 초기화가 최종적으로 실패했습니다. | 네트워크 상태를 확인하고 잠시 후 초기화를 재시도하세요. |

### 광고 로드 실패

| 코드 | 이름 | 발생 조건 | 권장 대응 |
| - | - | - | - |
| `204` | `NO_FILL` | 광고 요청은 성공했으나 노출 가능한 광고가 없습니다. | 광고가 없을 때 발생하는 정상적인 응답입니다. 잠시 후 다시 요청하세요. 지속되면 app-ads.txt 설정을 확인하세요. |
| `-5001` | `AD_LOAD_FAILED` | 요청한 광고를 로드하지 못했습니다. | 일시적 실패일 수 있습니다. 잠시 후 다시 요청하세요. |
| `-5603` | `INVALID_AD_UNIT_IDENTIFIER` | 잘못되었거나 비활성화된 Ad Unit Key, 앱 패키지명 불일치, 애드유닛 생성 직후 등입니다. | Ad Unit Key와 앱 패키지명 설정을 점검하세요. 애드유닛을 방금 생성했다면 반영에 30\~60분이 걸립니다. |

### 네트워크 오류

| 코드 | 이름 | 발생 조건 | 권장 대응 |
| - | - | - | - |
| `-1009` | `NO_NETWORK` | 기기가 인터넷에 연결되어 있지 않습니다. | 기기의 인터넷 연결 상태를 확인하세요. |
| `-1000` | `NETWORK_ERROR` | 일반적인 네트워크·서버 통신 오류입니다. | 잠시 후 다시 요청하세요. |
| `-1001` | `NETWORK_TIMEOUT` | 광고 요청이 제한 시간 안에 완료되지 않았습니다. | 잠시 후 다시 요청하세요. |

### 전체 화면 광고 상태 오류

전체 화면 광고(인터스티셜 광고·리워드 비디오 광고 등)의 로드/표시 순서가 맞지 않을 때 발생하는 오류입니다. 광고가 로드된 뒤 표시를 요청했는지 확인하세요.

| 코드 | 이름 | 발생 조건 | 권장 대응 |
| - | - | - | - |
| `-23` | `FULLSCREEN_AD_ALREADY_SHOWING` | 이미 전체 화면 광고가 표시 중인데 다른 전체 화면 광고를 표시하려 했습니다. | 별도 처리가 필요 없습니다. |
| `-24` | `FULLSCREEN_AD_NOT_READY` | 광고 로드가 완료되기 전에 표시를 시도했습니다. | 광고 로드 완료 후 표시하세요. |
| `-25` | `FULLSCREEN_AD_INVALID_VIEW_CONTROLLER` | 유효하지 않은 화면에서 전체 화면 광고를 표시하려 했습니다. | 유효한 화면(Activity)에서 광고를 표시하세요. |
| `-26` | `FULLSCREEN_AD_ALREADY_LOADING` | 이미 로딩 중인 전체 화면 광고를 다시 로드하려 했습니다. | 중복 로드 호출을 피하세요. |
| `-27` | `FULLSCREEN_AD_LOAD_WHILE_SHOWING` | 광고가 표시 중인데 동일한 광고를 다시 로드하려 했습니다. | 광고 표시가 끝난 후 다시 로드하세요. |

***

## 에러 처리 예시

로드 실패는 광고 포맷별 리스너의 `onAdLoadFail(error: DaroError)` 콜백으로 전달됩니다. `errorCodeName`으로 분기하세요.

```kotlin theme={null}
loader.setListener(object : DaroInterstitialAdLoaderListener {
    override fun onAdLoadSuccess(ad: DaroInterstitialAd, adInfo: DaroAdInfo) {
    }

    override fun onAdLoadFail(error: DaroError) {
        when (error.errorCodeName) {
            DaroErrorCode.NO_FILL,
            DaroErrorCode.AD_LOAD_FAILED -> retryLater()
            DaroErrorCode.NO_NETWORK,
            DaroErrorCode.NETWORK_ERROR,
            DaroErrorCode.NETWORK_TIMEOUT -> showNetworkGuide()
            DaroErrorCode.INVALID_AD_UNIT_IDENTIFIER -> reportConfigError(error.errorMessage)
            else -> retryLater()
        }
    }
})
```

<Note>
  기존 `onAdLoadFail(err: DaroAdLoadError)` 콜백은 하위 호환을 위해 그대로 유지되지만 **deprecated** 되었습니다. 기존 콜백과 새 콜백이 모두 호출되므로, 새 코드는 `onAdLoadFail(error: DaroError)`만 구현하는 것을 권장합니다.
</Note>