> ## 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 Android SDK's unified error codes (DaroErrorCode) 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 `DaroErrorCode` scheme, so publishers can handle errors with a single branching logic.

<Info>
  Available from daro-a `1.6.0` / daro-m `1.3.14`.
</Info>

***

## The DaroError object

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

| Property        | Type            | Description                                               |
| --------------- | --------------- | --------------------------------------------------------- |
| `errorCode`     | `Int`           | The integer value of the unified error code.              |
| `errorCodeName` | `DaroErrorCode` | The unified error code name (enum). Use it for branching. |
| `errorMessage`  | `String`        | The error message. Use it for logging and debugging.      |
| `latency`       | `Int`           | The time spent on the ad request, in milliseconds.        |

***

## Unified error codes

`DaroErrorCode` consists of the codes below. We recommend branching on `errorCodeName` (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 `errorMessage` and retry after a short delay.                   |
| `-2` | `NOT_INITIALIZED`       | An ad was requested before the SDK was initialized. | Request ads only after SDK initialization completes.                  |
| `-3` | `INITIALIZATION_FAILED` | 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`   | `NO_FILL`                    | 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` | `AD_LOAD_FAILED`             | The requested ad failed to load.                                                            | This may be a transient failure. Retry after a short delay.                                                                         |
| `-5603` | `INVALID_AD_UNIT_IDENTIFIER` | An invalid or disabled ad unit ID, an app package name mismatch, or a just-created ad unit. | Verify the ad unit ID and app package name settings. A newly created ad unit takes 30–60 minutes to propagate.                      |

### Network errors

| Code    | Name              | When it occurs                                         | Recommended action                      |
| ------- | ----------------- | ------------------------------------------------------ | --------------------------------------- |
| `-1009` | `NO_NETWORK`      | The device is not connected to the internet.           | Check the device's internet connection. |
| `-1000` | `NETWORK_ERROR`   | A general network or server communication failure.     | Retry after a short delay.              |
| `-1001` | `NETWORK_TIMEOUT` | 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` | `FULLSCREEN_AD_ALREADY_SHOWING`         | A fullscreen ad was already showing when another was requested to show. | No handling needed.                         |
| `-24` | `FULLSCREEN_AD_NOT_READY`               | Show was attempted before the ad finished loading.                      | Show the ad only after it finishes loading. |
| `-25` | `FULLSCREEN_AD_INVALID_VIEW_CONTROLLER` | A fullscreen ad was shown from an invalid screen.                       | Show the ad from a valid screen (Activity). |
| `-26` | `FULLSCREEN_AD_ALREADY_LOADING`         | A fullscreen ad already loading was requested to load again.            | Avoid duplicate load calls.                 |
| `-27` | `FULLSCREEN_AD_LOAD_WHILE_SHOWING`      | The same ad was requested to load again while it was showing.           | Load again after the ad finishes showing.   |

***

## Handling errors

Load failures are delivered to each ad format listener's `onAdLoadFail(error: DaroError)` callback. Branch on `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>
  The previous `onAdLoadFail(err: DaroAdLoadError)` callback is retained for backward compatibility but is **deprecated**. Both the existing and new callbacks fire, so new code should implement only `onAdLoadFail(error: DaroError)`.
</Note>