优聚智汇

简体中文

English

简体中文

English

外观

iOS 错误码 ​

概述 ​

本文档列出优聚智汇 iOS SDK 可能返回的错误码及其含义，帮助开发者快速排查和解决问题。

在 onLoadError 和 onAdError 回调中，开发者会收到 UjuException 对象，通过 error.code 和 error.message 获取错误信息。

iOS 错误码与 Android 不同

iOS 使用 UjuErrorCode 枚举（分组式：0 / 1-3 / 100-103 / 200-202 / ...），Android 使用 ErrorType 枚举（0 / 1000-2011）。请勿混淆两个平台的错误码，分别参考各平台错误码文档。

UjuException 结构 ​

swift
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)"
}

日志输出建议

打印错误时使用 error.description 或 String(describing: error)，不要使用 error.localizedDescription（后者会回退到 NSError 默认描述，如「未能完成操作。（UjuAdCore.UjuException错误5。）」）。

UjuErrorCode 错误码 ​

UjuErrorCode 枚举按业务分组定义：

初始化（Init） ​

错误码枚举名含义可能原因解决方案
0unknown未知错误未知原因联系技术支持并提供日志
1initFailed初始化失败appId/appKey 错误、网络问题、配置异常检查 appId/appKey/region，检查网络
2initInvalidConfig初始化配置无效UjuAdInitConfig.create 参数缺失或格式错误检查配置参数是否完整正确
3notInitializedSDK 未初始化未调用 initialize/start 就加载广告确保先完成两阶段初始化

加载（Load） ​

错误码枚举名含义可能原因解决方案
100loadFailed加载失败适配器异常、广告位配置错误检查广告位 ID，稍后重试
101loadTimeout加载超时广告请求超时检查网络状况，适当增加超时或重试
102noFill无填充优聚 ADX 无出价、聚合预算源无广告返回、广告库存不足、频次达上限正常业务响应，可降级或稍后重试
103invalidPlacement广告位无效placementId 为空或不存在检查广告位 ID 是否正确

展示（Show） ​

错误码枚举名含义可能原因解决方案
200showFailed展示失败展示流程异常检查展示时机与容器
201adNotReady广告未就绪未加载成功就调用 show确保 onLoadSuccess 后再 show，检查 isReady()
202frequencyCapped频次限制展示频次已达上限等待频次重置后再展示

网络（Network） ​

错误码枚举名含义可能原因解决方案
300networkError网络错误无网络连接检查网络连接
301networkTimeout网络超时网络请求超时检查网络状况，稍后重试
302networkUnavailable网络不可用网络完全不可用提示用户检查网络

解析（Parse） ​

错误码枚举名含义可能原因解决方案
400parseError解析错误数据格式异常联系技术支持
401encryptionError加密错误RSA/AES 加密失败检查 rsaPublicKey 是否正确
402decryptionError解密错误服务端数据解密失败检查 rsaPublicKey / 联系技术支持

配置（Config） ​

错误码枚举名含义可能原因解决方案
500configError配置错误策略配置异常联系技术支持
501configVersionMismatch配置版本不匹配本地缓存配置版本与服务端不一致清除缓存后重试

缓存（Cache） ​

错误码枚举名含义可能原因解决方案
600cacheError缓存错误缓存读写异常联系技术支持
601cacheIOError缓存 IO 错误磁盘读写失败检查磁盘空间

其他 ​

错误码枚举名含义可能原因解决方案
700crashReportFailed崩溃上报失败崩溃信息上报失败不影响主流程，可忽略
800adapterNotRegistered适配器未注册对应 ADN 适配器未注册检查 registerAdapterFactory 调用
801adapterInitFailed适配器初始化失败三方 SDK 初始化失败检查三方 SDK 配置
802adapterUnsupportedFormat适配器不支持该格式适配器不支持当前广告格式检查广告位与适配器匹配

onLoadError 与 onAdError 区分 ​

加载失败 vs 展示失败

  • onLoadError(error: UjuException)：广告加载阶段失败（1 个参数），常见错误码 1/2/100/101/102/103/300/301
  • onAdError(error: UjuException)：广告展示阶段失败（1 个参数），常见错误码 200/201/202

iOS 的 onLoadError 与 onAdError 均为 1 个参数（error），与 Android 不同（Android onLoadError 有 2 个参数含 placementId）。

错误处理示例 ​

swift
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)")
}

重试机制建议 ​

  • 对于网络错误（300/301/302）和加载超时（101），可实现合理的重试机制
  • 设置重试间隔和最大重试次数，避免无限重试
  • 建议重试间隔 3-5 秒，最大重试 3 次
  • noFill（102）不建议立即重试，可间隔较长时间后再试

常见问题排查表 ​

现象可能错误码排查方向
SDK 初始化失败1/2检查 appId/appKey/region 是否正确
广告不加载100/102/103检查广告位 ID、网络连接
广告不展示201确认 onLoadSuccess 后再 show，检查 isReady()
无填充102正常现象，广告库存不足，稍后重试
网络错误300/301/302检查网络连接
加解密失败401/402检查 rsaPublicKey 是否正确

联系技术支持 ​

如果您遇到无法解决的错误问题，可以通过以下方式联系技术支持：

提供错误码、错误信息、发生环境和复现步骤，有助于技术支持更快定位问题。

相关链接 ​