主题
错误码参考
文档版本 v1.0.0
本页对应 iOS SDK 1.0.0，与离线包 docs/ 目录里的同一份文档内容一致。其他版本见文档中心。
负数码是 AdMix 自己的，其余是广告平台的原始错误码，原样透传、没有做任何映射。 各端的 AdMix 错误码取值逐个一致。
| 平台 | 错误对象 | 来源平台 |
|---|---|---|
| Android | AdError，getCode() 取码 | AdError.adnType |
| iOS | NSError。AdMix 自身错误的 domain 为 AdMixErrorDomain，广告平台透传的为 AdMixAdnErrorDomain | userInfo[AdMixErrorAdnTypeKey]（AdMix 自身错误没有这个键） |
| uni-app | { code, message, adnType }，原样透传自底层原生 SDK | adnType（与广告平台无关的错误为空） |
AdMix 错误码
| 码 | 含义 | 处理 |
|---|---|---|
| -1001 | SDK 未初始化 | 检查第一步初始化（Android init、iOS setup）的调用位置，以及它与 start 的调用顺序 |
| -1002 | 广告位无配置 | 广告位标识拼错，或平台运营还没给这个广告位配广告源 |
| -1003 | 所有广告源均无填充 | 正常现象。按下方各平台的错误码定位是哪一家的问题，并检查平台广告位状态与填充率 |
| -1004 | 整体超时 | 请平台运营调大该广告位的 total_timeout_ms |
| -1005 | Adapter 不可用 | 该广告平台的适配器没被发现。Android 先看启动日志里有没有 adapter 就绪: xxx —— 没有就是依赖没引，或自定义打包策略把 META-INF/services/** 排除了；iOS 先看 适配器自检: 发现 […] 里有没有这一家 —— 没有就是子模块没引，或宿主链接参数缺 -ObjC |
| -1006 | 用户尚未同意隐私政策 | start 还没调就请求了广告。这是 SDK 的兜底红线：未同意时任何加载请求都不会碰到广告 SDK |
配置下发接口错误码
SDK 拉配置（/v1/config）与上报埋点（/v1/events）失败时，服务端返回 JSON 响应体 {"code": 错误码, "msg": "说明"}。拉配置失败时 SDK 把这两项原样打进日志 （远端配置拉取失败(404 code=40402)：…），所以下表的 msg 一栏就是设备日志里看到的字； 401 的三个鉴权码另打 SDK 内置的说明，排查动作与下表一致。
| HTTP 状态码 | 错误码 | 服务端 msg | 处理 |
|---|---|---|---|
| 404 | 40402 | 该应用尚未发布配置。请联系平台运营在管理后台「策略配置」中发布后重试 | 新应用最常见的情况：平台运营已录入平台应用 ID 与平台广告位，但尚未发布配置。将 AppID 提供给平台运营，发布后下次调用 start 即可拉到，宿主 App 无需改动 |
| 404 | 40401 | 应用不存在或已停止服务。请核对 AppID，或联系平台运营确认应用状态 | 核对代码中的 AppID 是否与管理后台一致；一致时联系平台运营确认应用状态 |
| 401 | 40101 | 签名校验失败。请核对 AppID 与 App 密钥是否与管理后台一致；App 密钥已作废时需更换为有效密钥 | 对照管理后台逐字核对 AppID 与 App 密钥，注意不要把 AppSecret 当成 App 密钥 |
| 401 | 40102 | 请求时间戳超出允许范围。请检查设备系统时间是否准确 | SDK 会按服务端时间自动校正并重试一次，偶发无需处理；持续出现时检查设备时间 |
| 401 | 40103 | 请求重复（nonce 已使用过）。请重新发起请求，并检查链路中是否有会重放请求的代理 | 检查链路中是否有会重放请求或按 URL 缓存的代理 |
| 400 | 40000 | 参数错误，后附具体原因（如缺少签名参数） | 使用 SDK 时不会出现；自行拼装请求时按 msg 补齐参数 |
应用或所属开发者被停用时，配置接口返回的是 HTTP 200 与一份空配置（没有任何广告位）， 而不是错误码 —— 端上表现为没有任何广告，已缓存的旧配置也会被替换。 排查方法见《配置与凭证》「拉不到配置的排查」。
iOS 系统网络错误
iOS 上拉配置失败时，系统层面的错误以 NSURLErrorDomain 的负数码出现在日志里， 与上表的 AdMix 错误码同为负数但互不相干。
| 码 | 含义 | 处理 |
|---|---|---|
| -1009 | 无网络连接 | 国行 iPhone 首次安装、用户尚未允许 App 使用无线数据时，全部请求都会报这个，日志会附带提示。用户允许后回到前台，SDK 自动重拉配置，见《初始化》「首次安装的网络授权」 |
| -1020 | 不允许使用蜂窝数据 | 用户在系统设置里关掉了该 App 的蜂窝数据，处理同上 |
| -1022 | 被 App Transport Security 拦截 | 出现在广告素材的下载上，表现为广告位有填充、画面缺图或空白。见《引入依赖》「网络安全配置」 |
iOS 启动失败排查
| 现象 | 原因 |
|---|---|
start 回调失败，错误码 -1002，日志「没有拿到任何 ADN 配置」 | 服务端下发的配置里没有任何广告平台。新建的应用需在管理后台审核通过并启用后才会下发配置，此前接口照常返回成功但内容为空 |
start 回调失败，日志含 -1009 与「允许 App 使用无线数据」 | 见上方「iOS 系统网络错误」 |
start 成功，加载回调 -1001「SDK 未就绪」 | 本地有旧配置，后台刷新后服务端返回的配置里已没有广告平台 |
穿山甲错误码
| 码 | 含义 | 怎么办 |
|---|---|---|
| 602 | 未知异常 | 平台广告位 ID 填成了 GroMore 瀑布流里的代码位 ID。穿山甲后台有两层 ID：「应用管理」页的广告位 ID（10 开头 9 位）是要填的那个，「瀑布流管理」里每一行的代码位 ID 平台不使用。错误信息毫无指向性，见《策略配置格式》「穿山甲后台配置」 |
| 20001 reason:234 | 聚合代码位只能在聚合场景使用 | SDK 没跑在聚合模式下，属开发侧问题 |
| 20001 reason:112 | 无效重复请求过多 | 测试期高频请求同一广告位时常见，换台设备或隔一会儿再试 |
| 20005 | 广告位下全部代码位均请求失败 | 要么瀑布流没配代码位，要么确实无填充 —— 按下方「区分瀑布流漏配与真无填充」判断 |
| 40006 | 广告位 ID 不合法 | 常见于 Banner 尺寸与后台广告位规格不匹配。把实际使用的 Banner 尺寸告知平台运营，按同一规格建广告位 |
区分瀑布流漏配与真无填充
开启 debug 时 SDK 会自动打开 GroMore 的错误明细开关，20005 的 message 里会带上每一家的 失败原因，形如：
text
csj 20005 [{"adn_name":"pangle","mediation_rit":"***","error_code":20001,"error_msg":"reason: 112 ..."}]| 方括号里 | 结论 |
|---|---|
| 是空的 | 瀑布流里一个代码位都没配，找平台运营在穿山甲后台「瀑布流管理」里补 |
| 有内容 | 瀑布流配了，是各家自己没填充。看里面每家的 error_msg |
优量汇错误码
| 码 | 含义 | 怎么办 |
|---|---|---|
| 107076 | 请求包名与在优量汇注册的媒体全包名一致才返回广告 | 包名与优量汇后台登记的不一致，见下方「两个包名字段」 |
| 5004 | 没有匹配到合适的广告资源 | 调试期正常无填充 —— 但包名不符时也可能报这个（实测返回码不稳定，有时 107076 有时 5004）。先按 107076 排查包名，排除后再当成真无填充 |
| 5006 | 包名校验错误 | 平台广告位被多个包名共用。优量汇广告位属于媒体、媒体绑定包名，不能共用，找平台运营为该应用单独建 |
| 107030 | App 包名无效 | 优量汇后台**「程序全包名」**填错，见下方「两个包名字段」 |
| 100133 | 广告位状态异常 / 新建未满 30 分钟 | 等 30 分钟，或找平台运营查后台状态 |
| 3003 | 网络不可用 | 检查设备网络 |
两个包名字段
最容易卡住的一条。优量汇后台有「主程序包名」和「程序全包名」两个字段， 服务端校验的是「程序全包名」。
两者不一致就报 107030，而错误文案只说「和注册时填写的一致」，不告诉是哪个字段。 向平台运营报包名时，把两个字段分别念出来逐字核对。
iOS 应用在优量汇后台登记的是 Bundle ID，排查思路相同。
日志里看不到具体广告位 ID
日志里的价格和平台广告位 ID 一律显示为 ***，与 debug 开关无关。 需要定位到具体广告位时，把广告位标识 + 广告平台 + 出问题的时间点交给平台运营查询。
报障时请一次给全：广告位标识、广告平台、出问题的时间点、原始日志、以及是 Debug 包还是 Release 包。 原始日志的取法：
| 平台 | 命令 / 工具 |
|---|---|
| Android | adb logcat -s "AdMix:V" |
| iOS | Xcode 控制台过滤 AdMix；不连 Xcode 时用「控制台」App 选中设备、搜索 subsystem:com.admix.sdk |
| uni-app | 日志由底层原生 SDK 打出，按 App 实际运行的平台用上面两行；需要在 initAdMix 时开 debug |