Ad Error Codes
Applies to Banner, interstitial, and rewarded video ads. See BannerAd.onError, InterstitialAd.onError, and RewardedVideoAd.onError for the error callback parameters.
| errCode | Description | Recommended action |
|---|---|---|
| -21001 | Invalid parameters, call order, or ad object state, such as an empty adUnitId, frequent requests, an ad not ready, or a destroyed instance | Check parameters and call order, and wait for onLoad before showing. Do not call show() after loading fails; create a new ad object after destruction. Avoid immediate retry loops when the frequency limit is reached |
| -22001 | Ad module initialization, configuration, or integration failure, or no eligible ad candidates; this code alone does not prove that backend ad configuration is missing | The CP must first enable advertising for the game in the OpenPaaS console and verify the ad unit ID and format. Use errMsg to check the integration, initialization, and configuration of the host ad module and ad-source adapters. For Banner ads, also compare the maximum container dimensions with the ad size; this code may occur when no candidate fits |
| -22005 | The ad configuration request failed, for example due to a network error or server rejection caused by invalid application or game configuration; refer to errMsg for the specific reason | Check network connectivity first. If errMsg contains a server-side failure, verify the application ID, game ID, application-to-game association, and platform configuration in the current environment; correct the configuration according to the returned reason instead of repeatedly retrying |
| -23001 | Ad load or display failure, possibly involving a timeout, an ad-source error, or an unusable auction result; this code alone does not establish a no-fill result | Address the specific reason in errMsg and avoid ineffective retries. Load again and wait for onLoad before showing |
| -29001 | Unclassified internal error | Record the complete errCode and errMsg, platform, app/SDK versions, ad format, ad unit ID, and reproduction steps, then contact technical support |
Creation-stage troubleshooting: If errMsg indicates that no matching ad placement was found (for example, No ad placement matches this adUnitId), first check whether advertising is enabled for the game in the console and whether the ad unit ID and format are correct. A successful ad/init response may still contain an empty ad unit list. Enable advertising and verify the configuration first; repeatedly calling load() or show() cannot resolve missing configuration.
Keep both the error code and the complete error message when investigating a failure:
errCodeis the unified error category exposed to the game. Araw_codeinerrMsgis an original error code from the corresponding layer, such as a server, ad SDK, or ad source; do not use it as a unified error code.- Diagnostic details such as
stage,format,sources, andraw_message, when present, can help identify the failure stage, ad format, and ad-source cause. Their content may vary by platform, version, and failure path, and they are not guaranteed to appear. Avoid parsing these text details to control application logic. - One error code can have multiple causes. Preserve the complete
errMsginstead of extracting only the error code.
