> ## 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.

# Error Handling

> How to handle ad load failures consistently with the DARO iOS SDK's unified error codes (DaroError.Code) and the DaroError object.

## Overview

When an ad fails to load, the DARO SDK delivers a unified error object, `DaroError`. Every error is converted into the same `DaroError.Code` scheme, so publishers can handle errors with a single branching logic.

***

## The DaroError object

The load-failure callback delivers a `DaroError` object. Its key properties are:

| Property               | Type             | Description                                               |
| ---------------------- | ---------------- | --------------------------------------------------------- |
| `code`                 | `DaroError.Code` | The unified error code name (enum). Use it for branching. |
| `message`              | `String`         | The error message. Use it for logging and debugging.      |
| `localizedDescription` | `String`         | An error description you can show to users or log.        |

`DaroError.Code` has an integer raw value. When needed, read the integer with `error.code.rawValue`.

***

## Unified error codes

`DaroError.Code` consists of the codes below. We recommend branching on `code` (the enum) rather than on the raw integer value.

### Initialization and configuration errors

| Code | Name                   | When it occurs                          | Recommended action                                                    |
| ---- | ---------------------- | --------------------------------------- | --------------------------------------------------------------------- |
| `-1` | `unspecified`          | A general, unclassified error.          | Check `message` and retry after a short delay.                        |
| `-2` | `notInitialized`       | Indicates the SDK is not initialized.   | Request ads only after SDK initialization completes.                  |
| `-3` | `initializationFailed` | SDK initialization failed conclusively. | Check the network state and retry initialization after a short delay. |

### Ad load failures

| Code    | Name                      | When it occurs                                                                            | Recommended action                                                                                                                  |
| ------- | ------------------------- | ----------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `204`   | `noFill`                  | The ad request succeeded, but no ad was available to show.                                | This is a normal response when no ad is available. Retry after a short delay. If it persists, check your app-ads.txt configuration. |
| `-5001` | `adLoadFailed`            | The requested ad failed to load.                                                          | This may be a transient failure. Retry after a short delay.                                                                         |
| `-5603` | `invalidAdUnitIdentifier` | An invalid or disabled ad unit ID, an app identifier mismatch, or a just-created ad unit. | Verify the ad unit ID and app identifier settings. A newly created ad unit takes 30–60 minutes to propagate.                        |

### Network errors

| Code    | Name             | When it occurs                                         | Recommended action                      |
| ------- | ---------------- | ------------------------------------------------------ | --------------------------------------- |
| `-1009` | `noNetwork`      | The device is not connected to the internet.           | Check the device's internet connection. |
| `-1000` | `networkError`   | A general network or server communication failure.     | Retry after a short delay.              |
| `-1001` | `networkTimeout` | The ad request did not complete within the time limit. | Retry after a short delay.              |

### Fullscreen ad state errors

These errors occur when the load/show order of fullscreen and rewarded ads is not correct. Most are internal SDK states and require no user-facing handling.

| Code  | Name                                | When it occurs                                                          | Recommended action                          |
| ----- | ----------------------------------- | ----------------------------------------------------------------------- | ------------------------------------------- |
| `-23` | `fullscreenAdAlreadyShowing`        | A fullscreen ad was already showing when another was requested to show. | No handling needed.                         |
| `-24` | `fullscreenAdNotReady`              | Show was attempted before the ad finished loading.                      | Show the ad only after it finishes loading. |
| `-25` | `fullscreenAdInvalidViewController` | A fullscreen ad was shown from an invalid view controller.              | Show the ad from a valid view controller.   |
| `-26` | `fullscreenAdAlreadyLoading`        | A fullscreen ad already loading was requested to load again.            | Avoid duplicate load calls.                 |
| `-27` | `fullscreenAdLoadWhileShowing`      | The same ad was requested to load again while it was showing.           | Load again after the ad finishes showing.   |

<Note>
  The unified code scheme shares the same values across iOS and Android. Among them, `notInitialized` (-2), `fullscreenAdAlreadyLoading` (-26), and `fullscreenAdLoadWhileShowing` (-27) are defined for cross-platform consistency but may not actually occur on iOS today.
</Note>

***

## Handling errors

Load failures are delivered to each ad format listener's `onAdLoadFail` closure. Branch on `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()
    }
}
```