附录C: 通道状态码大全与错误处理建议

在企业级统一通知通道平台中，准确的状态码定义和合理的错误处理机制是确保平台稳定运行、快速定位问题、提升用户体验的关键。本文档详细定义了统一通知平台中各类通道的状态码体系，并提供了针对性的错误处理建议和最佳实践。

状态码设计原则

统一通知平台的状态码设计遵循以下核心原则：

统一性原则

1. 全局唯一：所有状态码在平台内全局唯一，避免混淆
2. 层次化结构：采用层次化编码结构，便于分类和管理
3. 语义明确：每个状态码具有明确的业务含义

可扩展性原则

1. 预留空间：为未来扩展预留编码空间
2. 兼容性：新状态码不影响现有系统运行
3. 标准化：遵循行业标准和最佳实践

可读性原则

1. 简洁明了：状态码易于理解和记忆
2. 文档完善：提供详细的状态码说明文档
3. 示例丰富：提供典型的使用场景示例

状态码编码规范

编码结构

统一通知平台采用6位数字编码结构：

XXYYZZ
│││││└─ 错误细分（00-99）
││││└─── 子类错误（00-99）
│││└──── 主类错误（00-99）
││└───── 通道类型（00-99）
│└─────── 状态类型（00-99）
└──────── 系统级别（00-99）

通道类型编码

编码	通道类型	说明
01	SMS	短信通道
02	Email	邮件通道
03	Push	推送通道
04	Voice	语音通道
05	IM	即时消息通道
99	System	系统级错误

状态类型编码

编码	状态类型	说明
01	Processing	处理中
02	Success	成功
03	Failure	失败
04	Rejected	拒绝
05	Timeout	超时
06	Retry	重试
07	Cancelled	取消

SMS通道状态码

成功状态码（0102XX）

状态码	描述	说明
010200	SMS发送成功	短信已成功提交到运营商
010201	SMS送达成功	短信已成功送达用户终端
010202	SMS状态报告接收	已接收到运营商状态报告

处理中状态码（0101XX）

状态码	描述	说明
010100	SMS提交中	正在向运营商提交短信
010101	SMS排队中	短信在发送队列中等待
010102	SMS审核中	短信内容正在审核中

失败状态码（0103XX）

状态码	描述	说明	错误处理建议
010300	SMS发送失败	短信发送失败	检查网络连接，重试发送
010301	SMS内容审核失败	短信内容未通过审核	检查内容是否符合规范
010302	SMS手机号格式错误	手机号格式不正确	验证手机号格式
010303	SMS手机号为空	手机号不能为空	提供有效的手机号
010304	SMS内容超长	短信内容超过长度限制	缩短内容或分段发送
010305	SMS签名缺失	短信签名缺失	添加有效的短信签名
010306	SMS模板不匹配	使用的模板与内容不匹配	检查模板和内容一致性
010307	SMS余额不足	账户余额不足	充值账户余额
010308	SMS频率超限	发送频率超过限制	降低发送频率
010309	SMS黑名单	手机号在黑名单中	移除黑名单或更换号码
010310	SMS运营商拒绝	运营商拒绝接收	检查号码状态或联系运营商
010311	SMS网络错误	网络连接异常	检查网络连接后重试
010312	SMS通道维护	短信通道正在维护	等待维护完成或切换通道
010313	SMS通道拥塞	短信通道拥塞	等待或切换到备用通道
010314	SMS未知错误	未知错误	记录错误日志，联系技术支持

拒绝状态码（0104XX）

状态码	描述	说明	错误处理建议
010400	SMS发送被拒绝	短信发送被系统拒绝	检查发送策略和权限
010401	SMS权限不足	发送权限不足	申请相应权限
010402	SMS配额用完	发送配额已用完	申请更多配额或等待重置

Email通道状态码

成功状态码（0202XX）

状态码	描述	说明
020200	Email发送成功	邮件已成功提交到邮件服务器
020201	Email投递成功	邮件已成功投递到收件人邮箱
020202	Email打开确认	收件人已打开邮件

处理中状态码（0201XX）

状态码	描述	说明
020100	Email提交中	正在向邮件服务器提交邮件
020101	Email排队中	邮件在发送队列中等待
020102	Email审核中	邮件内容正在审核中

失败状态码（0203XX）

状态码	描述	说明	错误处理建议
020300	Email发送失败	邮件发送失败	检查网络连接，重试发送
020301	Email内容审核失败	邮件内容未通过审核	检查内容是否符合规范
020302	Email地址格式错误	邮箱地址格式不正确	验证邮箱地址格式
020303	Email地址为空	邮箱地址不能为空	提供有效的邮箱地址
020304	Email主题超长	邮件主题超过长度限制	缩短邮件主题
020305	Email内容超长	邮件内容超过大小限制	减少邮件内容或附件大小
020306	Email附件超限	邮件附件超过大小限制	减少附件大小或使用链接
020307	Email签名缺失	邮件签名缺失	添加有效的邮件签名
020308	Email模板不匹配	使用的模板与内容不匹配	检查模板和内容一致性
020309	Email余额不足	账户余额不足	充值账户余额
020310	Email频率超限	发送频率超过限制	降低发送频率
020311	Email黑名单	邮箱地址在黑名单中	移除黑名单或更换地址
020312	Email域名不存在	收件人域名不存在	验证邮箱地址有效性
020313	Email账号不存在	收件人账号不存在	验证邮箱地址有效性
020314	Email被拒收	邮件被收件人服务器拒收	检查邮件内容或联系收件人
020315	Email网络错误	网络连接异常	检查网络连接后重试
020316	Email通道维护	邮件通道正在维护	等待维护完成或切换通道
020317	Email通道拥塞	邮件通道拥塞	等待或切换到备用通道
020318	Email未知错误	未知错误	记录错误日志，联系技术支持

Push通道状态码

成功状态码（0302XX）

状态码	描述	说明
030200	Push发送成功	推送消息已成功提交到推送服务器
030201	Push送达成功	推送消息已成功送达设备
030202	Push已点击	用户已点击推送消息

处理中状态码（0301XX）

状态码	描述	说明
030100	Push提交中	正在向推送服务器提交消息
030101	Push排队中	推送消息在发送队列中等待

失败状态码（0303XX）

状态码	描述	说明	错误处理建议
030300	Push发送失败	推送消息发送失败	检查网络连接，重试发送
030301	Push设备标识无效	设备标识格式不正确或无效	验证设备标识有效性
030302	Push设备标识为空	设备标识不能为空	提供有效的设备标识
030303	Push设备离线	目标设备处于离线状态	等待设备上线后重试
030304	Push应用未安装	目标设备未安装应用	更换设备或安装应用
030305	Push应用未启动	目标应用未启动	启动应用或等待启动
030306	Push推送权限被禁	用户禁用了推送权限	引导用户开启推送权限
030307	Push消息超长	推送消息超过长度限制	缩短消息内容
030308	Push频率超限	推送频率超过限制	降低推送频率
030309	Push设备黑名单	设备在黑名单中	移除黑名单或更换设备
030310	Push网络错误	网络连接异常	检查网络连接后重试
030311	Push通道维护	推送通道正在维护	等待维护完成或切换通道
030312	Push通道拥塞	推送通道拥塞	等待或切换到备用通道
030313	Push证书过期	推送证书已过期	更新推送证书
030314	Push未知错误	未知错误	记录错误日志，联系技术支持

Voice通道状态码

成功状态码（0402XX）

状态码	描述	说明
040200	Voice呼叫成功	语音呼叫已成功建立
040201	Voice通话完成	语音通话已正常完成
040202	Voice用户接听	用户已接听语音呼叫

处理中状态码（0401XX）

状态码	描述	说明
040100	Voice呼叫中	正在建立语音呼叫连接
040101	Voice振铃中	语音呼叫正在振铃

失败状态码（0403XX）

状态码	描述	说明	错误处理建议
040300	Voice呼叫失败	语音呼叫建立失败	检查网络连接，重试呼叫
040301	Voice号码格式错误	电话号码格式不正确	验证电话号码格式
040302	Voice号码为空	电话号码不能为空	提供有效的电话号码
040303	Voice内容超长	语音内容超过长度限制	缩短语音内容
040304	Voice余额不足	账户余额不足	充值账户余额
040305	Voice频率超限	呼叫频率超过限制	降低呼叫频率
040306	Voice黑名单	电话号码在黑名单中	移除黑名单或更换号码
040307	Voice用户忙线	用户正在通话中	等待后重试呼叫
040308	Voice用户拒接	用户拒接呼叫	更换时间或号码重试
040309	Voice用户未接听	用户未接听呼叫	更换时间或方式重试
040310	Voice网络错误	网络连接异常	检查网络连接后重试
040311	Voice通道维护	语音通道正在维护	等待维护完成或切换通道
040312	Voice通道拥塞	语音通道拥塞	等待或切换到备用通道
040313	Voice未知错误	未知错误	记录错误日志，联系技术支持

IM通道状态码

成功状态码（0502XX）

状态码	描述	说明
050200	IM消息发送成功	IM消息已成功发送
050201	IM消息已读	IM消息已被用户阅读
050202	IM消息已回复	IM消息已收到用户回复

处理中状态码（0501XX）

状态码	描述	说明
050100	IM消息提交中	正在向IM服务器提交消息
050101	IM消息排队中	IM消息在发送队列中等待

失败状态码（0503XX）

状态码	描述	说明	错误处理建议
050300	IM消息发送失败	IM消息发送失败	检查网络连接，重试发送
050301	IM用户标识无效	用户标识格式不正确或无效	验证用户标识有效性
050302	IM用户标识为空	用户标识不能为空	提供有效的用户标识
050303	IM用户离线	目标用户处于离线状态	等待用户上线后重试
050304	IM应用未安装	目标用户未安装应用	更换用户或引导安装应用
050305	IM应用未启动	目标应用未启动	启动应用或等待启动
050306	IM消息权限被禁	用户禁用了消息权限	引导用户开启消息权限
050307	IM消息超长	IM消息超过长度限制	缩短消息内容
050308	IM频率超限	消息发送频率超过限制	降低发送频率
050309	IM用户黑名单	用户在黑名单中	移除黑名单或更换用户
050310	IM网络错误	网络连接异常	检查网络连接后重试
050311	IM通道维护	IM通道正在维护	等待维护完成或切换通道
050312	IM通道拥塞	IM通道拥塞	等待或切换到备用通道
050313	IM未知错误	未知错误	记录错误日志，联系技术支持

系统级状态码

成功状态码（9902XX）

状态码	描述	说明
990200	系统处理成功	系统请求处理成功
990201	系统配置更新成功	系统配置更新成功
990202	系统任务执行成功	系统任务执行成功

失败状态码（9903XX）

状态码	描述	说明	错误处理建议
990300	系统内部错误	系统内部发生未预期错误	记录错误日志，联系技术支持
990301	系统配置错误	系统配置不正确	检查并修正系统配置
990302	系统资源不足	系统资源不足	扩容系统资源
990303	系统服务不可用	系统服务暂时不可用	等待服务恢复
990304	系统维护中	系统正在进行维护	等待维护完成
990305	系统超时	系统处理超时	检查系统负载，优化性能
990306	数据库错误	数据库操作失败	检查数据库连接和状态
990307	缓存错误	缓存操作失败	检查缓存服务状态
990308	网络错误	网络连接异常	检查网络连接状态
990309	认证失败	身份认证失败	检查认证信息
990310	权限不足	操作权限不足	申请相应操作权限

错误处理最佳实践

重试策略

1. 指数退避重试：

   • 第一次失败后等待1秒重试
   • 第二次失败后等待2秒重试
   • 第三次失败后等待4秒重试
   • 最多重试3次

2. 针对性重试：

   • 对于网络错误、超时等临时性错误进行重试
   • 对于参数错误、权限不足等永久性错误不进行重试

降级策略

1. 通道降级：

   • 短信发送失败时降级为邮件通知
   • 推送通知失败时降级为短信通知
   • 建立多通道备用机制

2. 功能降级：

   • 非核心功能在系统压力大时自动降级
   • 保证核心发送功能的稳定性

熔断机制

1. 错误率熔断：

   • 当某个通道错误率超过阈值时自动熔断
   • 熔断后暂停该通道的使用
   • 定期尝试恢复通道服务

2. 超时熔断：

   • 当通道响应时间持续超时自动熔断
   • 防止慢通道影响整体性能

监控告警

1. 实时监控：

   • 监控各通道的成功率、失败率、响应时间
   • 监控系统资源使用情况
   • 监控关键业务指标

2. 告警机制：

   • 设置合理的告警阈值
   • 多渠道告警通知
   • 告警分级处理

日志记录规范

日志级别

1. DEBUG：详细调试信息，用于开发和问题排查
2. INFO：一般信息，记录系统正常运行状态
3. WARN：警告信息，可能影响系统功能但不会导致失败
4. ERROR：错误信息，导致功能失败的错误
5. FATAL：致命错误，导致系统无法继续运行

日志内容

1. 请求日志：

   • 请求时间、请求ID、用户ID
   • 请求参数、请求地址
   • 响应状态码、响应时间

2. 错误日志：

   • 错误时间、错误码、错误信息
   • 请求上下文信息
   • 堆栈跟踪信息

3. 审计日志：

   • 操作时间、操作用户、操作类型
   • 操作对象、操作结果
   • IP地址、设备信息

结语

完善的通道状态码体系和科学的错误处理机制是统一通知平台稳定运行的重要保障。通过定义清晰的状态码、实施合理的错误处理策略、建立完善的监控告警体系，我们可以快速定位和解决问题，提升平台的可靠性和用户体验。

在实际应用中，建议根据具体的业务场景和技术架构，合理配置状态码和错误处理策略。同时，要建立完善的日志记录和监控体系，为问题排查和系统优化提供数据支撑。

随着业务的发展和技术的进步，状态码体系和错误处理机制也需要不断优化和完善。我们应该保持对新技术和新方法的关注，持续改进错误处理能力，确保平台的先进性和竞争力。