iOS Error Codes

Overview

This document lists the error codes that the UjuAd iOS SDK may return and their meanings, helping developers quickly troubleshoot and resolve issues.

In the onLoadError and onAdError callbacks, developers receive a UjuException object and obtain error information via error.code and error.message.

iOS Error Codes Differ from Android

iOS uses the UjuErrorCode enum (grouped: 0 / 1-3 / 100-103 / 200-202 / ...), while Android uses the ErrorType enum (0 / 1000-2011). Do not confuse the error codes of the two platforms; refer to each platform's error code documentation separately.

UjuException Structure

public struct UjuException: Error, CustomStringConvertible {
    public let code: Int                  // 错误码，对应 UjuErrorCode.rawValue
    public let message: String            // 错误信息
    public let underlyingError: Error?    // 底层错误（可选，用于调试）
    public var description: String { get } // "UjuException(code=X, message=Y)"
}

Log Output Recommendations

When printing errors, use error.description or String(describing: error). Do not use error.localizedDescription (which falls back to NSError's default description, such as "The operation couldn't be completed. (UjuAdCore.UjuException error 5.)").

UjuErrorCode Error Codes

The UjuErrorCode enum is defined by business group:

Init

Error Code	Enum Name	Meaning	Possible Cause	Solution
0	unknown	Unknown error	Unknown cause	Contact technical support and provide logs
1	initFailed	Initialization failed	Incorrect appId/appKey, network issues, configuration errors	Check appId/appKey/region, check network
2	initInvalidConfig	Invalid initialization configuration	UjuAdInitConfig.create parameters missing or malformed	Check that configuration parameters are complete and correct
3	notInitialized	SDK not initialized	Loading ads before calling initialize/start	Ensure two-phase initialization is completed first

Load

Error Code	Enum Name	Meaning	Possible Cause	Solution
100	loadFailed	Load failed	Adapter exception, ad placement configuration error	Check ad placement ID, retry later
101	loadTimeout	Load timeout	Ad request timed out	Check network conditions, increase timeout or retry appropriately
102	noFill	No fill	ADX had no bid this time, insufficient ad inventory, frequency cap reached	Normal business response; can fall back or retry later
103	invalidPlacement	Invalid ad placement	placementId is empty or does not exist	Check that the ad placement ID is correct

Show

Error Code	Enum Name	Meaning	Possible Cause	Solution
200	showFailed	Show failed	Display process exception	Check display timing and container
201	adNotReady	Ad not ready	Called show before load success	Ensure show is called after onLoadSuccess, check isReady()
202	frequencyCapped	Frequency capped	Display frequency limit reached	Wait for frequency reset before displaying

Network

Error Code	Enum Name	Meaning	Possible Cause	Solution
300	networkError	Network error	No network connection	Check network connection
301	networkTimeout	Network timeout	Network request timed out	Check network conditions, retry later
302	networkUnavailable	Network unavailable	Network completely unavailable	Prompt user to check network

Parse

Error Code	Enum Name	Meaning	Possible Cause	Solution
400	parseError	Parse error	Data format exception	Contact technical support
401	encryptionError	Encryption error	RSA/AES encryption failed	Check that rsaPublicKey is correct
402	decryptionError	Decryption error	Server data decryption failed	Check rsaPublicKey / contact technical support

Config

Error Code	Enum Name	Meaning	Possible Cause	Solution
500	configError	Configuration error	Strategy configuration exception	Contact technical support
501	configVersionMismatch	Configuration version mismatch	Local cached config version inconsistent with server	Clear cache and retry

Cache

Error Code	Enum Name	Meaning	Possible Cause	Solution
600	cacheError	Cache error	Cache read/write exception	Contact technical support
601	cacheIOError	Cache IO error	Disk read/write failure	Check disk space

Others

Error Code	Enum Name	Meaning	Possible Cause	Solution
700	crashReportFailed	Crash report failed	Crash information upload failed	Does not affect main flow; can be ignored
800	adapterNotRegistered	Adapter not registered	Corresponding ADN adapter not registered	Check registerAdapterFactory call
801	adapterInitFailed	Adapter initialization failed	Third-party SDK initialization failed	Check third-party SDK configuration
802	adapterUnsupportedFormat	Adapter does not support this format	Adapter does not support current ad format	Check ad placement and adapter compatibility

onLoadError vs onAdError

Load Failure vs Show Failure

• onLoadError(error: UjuException): Ad load phase failure (1 parameter), common error codes 1/2/100/101/102/103/300/301
• onAdError(error: UjuException): Ad show phase failure (1 parameter), common error codes 200/201/202

Both onLoadError and onAdError on iOS take 1 parameter (error), unlike Android (Android's onLoadError has 2 parameters including placementId).

Error Handling Example

func onLoadError(error: UjuException) {
    switch error.code {
    case UjuErrorCode.noFill.rawValue:
        // ADX 无出价，正常业务响应，可降级到其他广告源
        print("无填充，稍后重试")
    case UjuErrorCode.networkError.rawValue, UjuErrorCode.networkTimeout.rawValue:
        // 网络问题，提示用户检查网络
        print("网络异常，请检查网络连接")
    case UjuErrorCode.adNotReady.rawValue:
        // 广告未就绪，需先调用 load()
        print("广告未就绪，请先加载")
    default:
        print("广告错误: \(error.description)")
    }
}

func onAdError(error: UjuException) {
    // 展示阶段失败
    print("展示失败: code=\(error.code), msg=\(error.message)")
}

Retry Mechanism Recommendations

• For network errors (300/301/302) and load timeout (101), implement a reasonable retry mechanism
• Set retry intervals and maximum retry counts to avoid infinite retries
• Recommended retry interval of 3-5 seconds, maximum 3 retries
• noFill (102) is not recommended for immediate retry; wait a longer interval before retrying

Common Troubleshooting Table

Symptom	Possible Error Code	Troubleshooting Direction
SDK initialization failure	1/2	Check if appId/appKey/region is correct
Ad does not load	100/102/103	Check ad placement ID, network connection
Ad does not show	201	Confirm show is called after onLoadSuccess, check isReady()
No fill	102	Normal phenomenon, insufficient ad inventory, retry later
Network error	300/301/302	Check network connection
Encryption/decryption failure	401/402	Check if rsaPublicKey is correct

Contact Technical Support

If you encounter error issues that cannot be resolved, you can contact technical support via:

• Email: marco@ujuad.com
• Website: https://www.ujuad.com

Providing the error code, error message, environment, and reproduction steps will help technical support locate the issue faster.

Related Links

• iOS FAQ
• iOS SDK Initialization
• iOS Integration Preparation
• API Reference