> ## 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 iOS SDK의 통합 에러 코드(DaroError.Code)와 DaroError 객체로 광고 로드 실패를 일관되게 처리하는 방법을 안내합니다.

## 개요

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

***

## DaroError 객체

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

| 프로퍼티                   | 타입               | 설명                                   |
| ---------------------- | ---------------- | ------------------------------------ |
| `code`                 | `DaroError.Code` | 통합 에러 코드의 이름(enum)입니다. 분기 처리에 사용하세요. |
| `message`              | `String`         | 오류 메시지입니다. 로깅·디버깅에 활용하세요.            |
| `localizedDescription` | `String`         | 사용자에게 표시하거나 로깅할 수 있는 오류 설명입니다.       |

`DaroError.Code`는 정수 raw value를 가집니다. 필요하면 `error.code.rawValue`로 정수 값을 확인할 수 있습니다.

***

## 통합 에러 코드

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

### 초기화·설정 오류

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

### 광고 로드 실패

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

### 네트워크 오류

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

### 전면 광고 상태 오류

전면·보상형 광고의 로드/표시 순서가 맞지 않을 때 발생하는 오류입니다. 대부분 SDK 내부 상태로 별도의 사용자 노출이 필요하지 않습니다.

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

<Note>
  통합 코드 체계는 iOS와 Android가 동일한 값을 공유합니다. 이 중 `notInitialized`(-2), `fullscreenAdAlreadyLoading`(-26), `fullscreenAdLoadWhileShowing`(-27)은 플랫폼 간 일관성을 위해 정의되어 있으나 현재 iOS에서는 실제로 발생하지 않을 수 있습니다.
</Note>

***

## 에러 처리 예시

로드 실패는 광고 포맷별 리스너의 `onAdLoadFail` 클로저로 전달됩니다. `error.code`로 분기하세요.

```swift theme={null}
daroInterstitialLoader.listener.onAdLoadFail = { error in
    switch error.code {
    case .noFill, .adLoadFailed:
        retryLater()
    case .noNetwork, .networkError, .networkTimeout:
        showNetworkGuide()
    case .invalidAdUnitIdentifier:
        reportConfigError(error.message)
    default:
        retryLater()
    }
}
```