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

***

## 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 Key, an app package name mismatch, or a just-created Ad Unit. | Verify the Ad Unit Key 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 ads (including interstitial and rewarded video ads) is not correct. Check that the ad has loaded before requesting display.

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