> ## 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 Key, an app identifier mismatch, or a just-created Ad Unit. | Verify the Ad Unit Key and Integration Key for the target app. 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 ads (including interstitial and rewarded video 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()
    }
}
```