错误处理（4.x）-阿里云帮助中心

本文介绍 Android SDK 4.x 的初始化、API、ACCS 通道和厂商 Token 相关错误，以及通过统一日志 TAG EMAS_PUSH 排查问题的方法。

先获取回调和日志

适用范围：移动推送 Android SDK 4.x，以下错误码和回调行为以已发布的 4.0.0 为基线。先确定应用实际依赖版本，再记录发生错误的 API、CommonCallback.onFailed(String errorCode, String errorMessage) 两个参数及发生时间。PUSH_00000 是 SDK 的成功码定义，业务代码应根据对应接口的成功回调判断结果。

在 PushServiceFactory.init 完成后、register 以及厂商通道注册前设置日志等级。setDebug(true) 用于接入时的组件和参数检查，日志输出等级通过 setLogLevel 设置。请在 Application 中完成初始化后执行以下示例：

CloudPushService pushService = PushServiceFactory.getCloudPushService();
pushService.setLogLevel(CloudPushService.LOG_DEBUG);
pushService.setDebug(true); // 可选：调试组件和参数配置。
pushService.register(getApplicationContext(), new CommonCallback() {
    @Override
    public void onSuccess(String response) {
        // 在主进程确认注册结果，再读取 pushService.getDeviceId()。
    }

    @Override
    public void onFailed(String errorCode, String errorMessage) {
        // PushDemo 是应用自己的 TAG，不属于 SDK 统一 TAG。
        Log.e("PushDemo", "register failed: " + errorCode + " | " + errorMessage);
    }
});

Android Studio Logcat 使用 tag:EMAS_PUSH level:DEBUG 查看 SDK 日志；命令行使用以下过滤条件。示例中应用自定义的 PushDemo 回调日志需单独查看，或在命令中同时添加该 TAG。

adb logcat -v threadtime "EMAS_PUSH:D" "*:S"
# 同时查看示例应用的失败回调：
adb logcat -v threadtime "EMAS_PUSH:D" "PushDemo:D" "*:S"

4.x SDK 日志统一使用 TAG EMAS_PUSH，[AppRegister]、[AgooChannel] 等模块名位于日志正文。厂商原生 SDK、Android 系统和应用日志使用各自的 TAG。调试结束后请降低日志等级；LOG_OFF 仅关闭 SDK 统一日志管道的输出，其他来源的日志由各自的日志配置控制。

重要

4.x 不以旧版 MPS:、awcn、AUTH_SUCC、ACCS/SPDY 日志或旧 channel 数值作为通道成功判据。旧 1105、10207 和 ACCS 错误处理请参见错误处理（3.x）；升级改动参见 Android SDK 4.x升级指南。

初始化和 API 调用错误

下表列出 Android SDK 4.0.0 的常见错误码及处理方法。errorMessage 中包含具体参数、服务端响应或异常信息，排查时请同时记录错误码和完整错误信息。

错误码	含义	处理方式
`PUSH_20101`	参数输入非法	检查当前接口参数；例如 register 的 Context 不能为空。
`PUSH_20103`	appversion 参数错误	检查应用版本号，不能为 null，长度不能超过 32 位；此项在开启 setDebug(true) 时检查。
`PUSH_20106`	核心组件未配置	开启 setDebug(true) 后，SDK 会检查必需组件。请按 4.x 接入文档核对最终合并的 AndroidManifest.xml，以及主 SDK 和厂商适配器的依赖与混淆配置。
`PUSH_20108`	未初始化	先在当前进程执行 PushServiceFactory.init，再取得 CloudPushService 并调用相关接口。
`PUSH_20109`	废弃接口	调用了已废弃的接口，请改用 4.x 文档中支持的接口。
`PUSH_20110`	已经调用注册，重复调用无效	检查 Application、业务入口及多进程中的 register 调用，确保同一注册流程只触发一次。SDK 会自动重试注册；应用主动重试前，请先根据失败回调和日志处理错误原因。
`PUSH_10114`	内部错误	保留异常及前后日志，检查 SDK 和适配器版本是否匹配；结合具体 errorMessage 排查。
`PUSH_10115`	通道注册状态异常	查看注册开始到失败之间的完整日志，检查调用顺序、重复注册与 ACCS 初始化结果。
`PUSH_10119`	非主进程不用初始化	该信息表示注册流程执行了进程检查。请在各进程中完成 PushServiceFactory.init，并在主进程中检查 register 结果。
`PUSH_10120`	推送注册超时	Android SDK 4.0.0 等待 ACCS 通道结果超时时，errorMessage 包含 channel timeout。请检查错误发生时的网络状态，以及连接建立和注册过程中的日志。

说明

非主进程收到 onSuccess 时，请继续在主进程中验证注册和消息接收结果。请按 Application 初始化要求，在各进程中完成初始化。

如遇 PUSH_10109（网络连接失败）或 PUSH_20107（连续崩溃导致推送服务关闭），请记录完整错误日志及主 SDK、辅助通道 SDK 和厂商扩展包版本，联系技术支持排查。

服务端接口和网络请求错误

错误码	默认含义	处理方式
`PUSH_10101`	参数缺失	检查调用接口和服务端返回的具体缺失字段。
`PUSH_10102`	参数无效	按当前接口参数要求校验取值、长度与格式。
`PUSH_10103`	服务端签名与客户端不匹配	检查 AppKey、AppSecret 是否来自同一应用，以及构建变体和初始化配置是否对应目标环境。日志中请对密钥进行脱敏。
`PUSH_10104`	Tag 相关错误	按 errorMessage 检查标签数量、长度、目标和接口参数。
`PUSH_10105`	Alias 相关错误	按 errorMessage 检查别名及绑定/解绑操作。
`PUSH_10106`	服务端内部错误	保留发生时间、调用接口、错误码和已脱敏的错误信息；持续出现时联系技术支持。
`PUSH_10107`	网络 IO 错误	检查网络连通性和异常详情；排查代理、VPN 或网络切换等实际环境因素。
`PUSH_10108`	返回结果解析错误	记录异常信息与 SDK 版本，检查网络代理及服务端响应内容，并结合完整 errorMessage 定位原因。
`PUSH_10118`	其它接口错误	未单独映射的服务端错误。errorMessage 会包含服务端错误码和消息，应一并保留。
`PUSH_10121`	网络请求失败，请检查网络是否可用	检查获取设备信息等请求的网络错误详情及同一时间段 SDK 日志。

errorMessage 可能包含服务端返回的具体错误信息。参数或业务校验失败时，请先修正参数或业务配置；网络失败时，再按应用的重试策略重试。

ACCS 自有通道错误

4.x 自有通道使用 ACCS 长连接。下表列出通道层错误码，register 回调中的错误码格式见表后说明。注册完成后的连接变化请通过对应时段的连接日志排查。

通道错误码	默认含义	处理方式
`PUSH_30001`	服务器返回非成功的业务错误码	查看同一操作的服务端错误详情。注册和推送开关等操作都可能出现，应记录具体 API。
`PUSH_30002`	长连接网络错误	检查 ACCS 连接是否存在、网络状态及异常原因；结合连接建立或请求失败日志定位。
`PUSH_30003`	内部错误	保留异常堆栈与前后日志，结合具体注册或开关操作排查。
`PUSH_30004`	context 为空	检查 PushServiceFactory.init 是否已在当前进程完成，是否使用正确的 Application。
`PUSH_30005`	长连通道未就绪	该错误可能出现在启用或关闭推送时。请先完成主进程的注册，确认 ACCS 通道就绪后再执行推送开关操作。
`PUSH_30006`	设备 UTDID 无效	SDK 收到此关闭原因后会尝试重新生成 UTDID。完整退出并重新启动应用后验证；仍复现时保留日志联系技术支持。
`PUSH_30007`	设备 UTDID 冲突	检查设备镜像、克隆或标识复用情况，记录冲突日志并联系技术支持确认处理方式。
`PUSH_30008`	设备 ID 在黑名单中	请联系技术支持核查服务端设备限制及恢复方式。

重要

Android SDK 4.0.0 的 register 流程会为通道错误码添加 PUSH_ 前缀。例如，通道返回 PUSH_30002 时，注册失败回调中的错误码为 PUSH_PUSH_30002。推送开关等直接传递通道结果的接口使用单前缀，例如 PUSH_30005。排查时请记录调用接口及原始 errorCode、errorMessage，按对应接口的格式识别错误。

连接创建失败时，注册回调还可能返回符号型错误码，例如 CONNECTION_CREATION_FAILED 在注册流程中转换为 PUSH_CONNECTION_CREATION_FAILED。ACCS 日志中的异常类型包括 CONNECTION_ALREADY_CLOSED、CONNECTION_ALREADY_EXISTED、CONNECTION_NOT_EXISTED、CONNECTION_CREATION_FAILED、READ_TIMEOUT、WRITE_TIMEOUT 和 INTERNAL_ERROR。部分异常会转换为通用通道错误后返回应用；请结合回调中的 errorCode、errorMessage 和同一时段的连接日志定位具体原因。

在日志正文中定位 [AgooChannel] 模块，查找 Failed to build、AgooChannel initialization failed、connection closed: 和 Channel not ready 等关键字，并结合相邻日志确定错误发生在连接建立、注册、推送开关还是连接关闭阶段。

厂商注册和 Token 上报排查

厂商 SDK 的错误码不是统一 PUSH 错误码。统一日志 TAG 只统一日志入口，不会改变厂商返回的错误码和含义。先确认厂商注册拿到有效 token，再确认 SDK 向 EMAS 上报的流程，最后用实际推送验证接收、展示和点击。

厂商	日志正文模块	注册结果关键词	核查重点
小米	`[MiPushBroadcastReceiver]`	`onReceiveRegisterResult regId:`	确认注册结果成功且 regId 有效。
华为	`[HuaWeiRegister] / [HuaweiPushMessageService]`	`onToken appId: / onToken token:`	确认 token 非空；失败时保留厂商 statusCode 或异常信息。
荣耀	`[HonorRegister] / [HonorPushMessageService]`	`onToken appId: / onToken token:`	确认取得非空 token；失败时记录 errorCode 和 errorMsg 并排查对应原因。
OPPO	`[OppoRegister]`	`onRegister code=0 regid=`	注册成功需同时满足 code 为 0，且 regid 为有效注册标识；regid 为错误文本时，请按错误内容排查。
vivo	`[VivoRegister] / [PushMessageReceiverImpl]`	`onReceiveRegId regId:`	确认 regId 有效，并检查 turnOnPush、getRegId 的结果及 onFailed 信息。
魅族	`[MeizuPushReceiver]`	`onRegister status:`	检查注册结果，确认 pushId 为有效注册标识。
FCM	`[GcmRegister]`	`fcm token is`	确认取得非空 token，并继续检查向 EMAS 上报的结果。

表中的关键字用于定位厂商注册日志。注册结果请结合返回状态和有效 token 确认；注册失败时，请记录厂商原始错误码、错误消息，并核对对应厂商平台的配置。

阶段	4.x 日志关键词	含义与处理
`EMAS_PUSH / [AgooChannel]`	`reportThirdToken: type=`	开始上报 token，请继续检查后续上报结果。
`EMAS_PUSH / [AgooChannel]`	`Channel not ready, enqueuing token request:`	自有通道尚未就绪，SDK 暂存 token 上报请求。继续检查主进程注册和 ACCS 通道状态，并观察后续处理。
`EMAS_PUSH / [AgooTokenReportService]`	`connection not found`	上报时未取得连接，检查同一时间的通道初始化和连接状态。
`EMAS_PUSH / [AgooChannel]`	`Token report success:`	SDK 的 token 上报请求与响应流程已完成。接下来请在控制台核对设备信息，并发送测试通知验证接收、展示和点击。
`EMAS_PUSH / [AgooChannel]`	`Token report failed: / Token report error:`	上报未完成或出现异常，继续查同一时间的上报服务异常和 ACCS 日志。

厂商 token 注册成功与 EMAS 上报成功是不同阶段。确认上报后，分别验证应用在前台、后台和进程不在时的适用通道；检查系统通知权限、Android 通知渠道配置和通知内容。4.x 点击业务统一在 onNotificationOpened 中处理，小米、华为、荣耀、OPPO、vivo、魅族等原生厂商通知点击仍需正确配置中转 Activity。旧 onSysNoticeOpened 回调只用于 3.x。FCM data 消息不以该 Activity 为必需条件。

提交排障信息

问题仍未解决时，提供主 SDK 与厂商适配器的准确版本、Android 版本和机型、发生问题的 API、运行进程、发生时间、原始 errorCode/errorMessage，以及从初始化到失败的相关日志。说明是否已取得有效 DeviceId、厂商 token 是否取得和上报、问题发生在接收/展示/点击哪个阶段。

DeviceId、UTDID、厂商 token 是不同标识，不可互换。提交前对日志中的设备标识、账号、token 和业务内容进行必要脱敏，不提供 AppSecret 等密钥。调试日志只保留定位所需范围。