报错处理手册

常见错误码及处理方法

概述

本文档汇总了系统中常见的错误码及其含义，帮助技术支持人员快速定位和处理问题。

错误码分类

系统错误 (1xxx)

错误码	错误信息	原因	解决方案
1001	系统内部错误	服务器异常	查看日志，联系开发
1002	服务不可用	服务暂时不可用	检查服务状态
1003	请求超时	处理时间过长	优化请求或重试
1004	限流触发	请求频率过高	降低请求频率

认证错误 (2xxx)

错误码	错误信息	原因	解决方案
2001	Token 无效	Token 过期或错误	重新登录获取
2002	Token 已过期	超过有效期	刷新 Token
2003	权限不足	无操作权限	检查用户权限
2004	账号已禁用	账号被禁用	联系管理员

参数错误 (3xxx)

错误码	错误信息	原因	解决方案
3001	参数缺失	必填参数未提供	补充必填参数
3002	参数格式错误	格式不符合要求	检查参数格式
3003	参数值非法	值不在允许范围内	修正参数值
3004	数据重复	唯一约束冲突	检查数据唯一性

业务错误 (4xxx)

错误码	错误信息	原因	解决方案
4001	资源不存在	ID 错误或已删除	确认资源 ID
4002	资源已存在	重复创建	使用已有资源
4003	状态不匹配	当前状态不允许操作	检查资源状态
4004	依赖缺失	前置条件不满足	先完成前置操作

排查步骤

通用排查流程

graph TD
    A[收到错误报告] --> B[获取错误码]
    B --> C{是否已知错误?}
    C -->|是| D[查阅对应解决方案]
    C -->|否| E[收集详细信息]
    E --> F[查看日志]
    F --> G[分析原因]
    G --> H[制定解决方案]
    D --> I[执行修复]
    H --> I
    I --> J[验证结果]

信息收集清单

遇到未知错误时，收集以下信息：

• [ ] 错误码和错误信息
• [ ] 发生时间
• [ ] 操作步骤
• [ ] 请求参数
• [ ] 返回结果
• [ ] 相关日志
• [ ] 环境信息（版本、配置等）

常见场景

场景一：登录失败

错误码： 2001

可能原因：

1. Token 过期
2. Token 被篡改
3. 用户在其他设备登录导致 Token 失效

解决方案：

# 1. 确认 Token 状态
curl -H "Authorization: Bearer {token}" \
  https://api.example.com/v1/auth/check

# 2. 重新获取 Token
curl -X POST https://api.example.com/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"xxx","password":"xxx"}'

场景二：数据查询失败

错误码： 4001

可能原因：

1. 资源 ID 错误
2. 资源已被删除
3. 无权限查看该资源

解决方案：

# 1. 确认资源是否存在
curl https://api.example.com/v1/resources/{id} \
  -H "Authorization: Bearer {token}"

# 2. 检查权限
curl https://api.example.com/v1/users/me/permissions \
  -H "Authorization: Bearer {token}"

日志定位

关键日志路径

服务	日志路径	说明
Nginx	/var/log/nginx/error.log	访问错误
应用	/var/log/app/error.log	业务错误
数据库	/var/log/mysql/error.log	数据库错误

常用搜索命令

# 按错误码搜索
grep "ERROR.*1001" /var/log/app/error.log

# 按时间范围搜索
sed -n '/2026-01-15 10:00/,/2026-01-15 11:00/p' /var/log/app/error.log

# 统计错误出现次数
grep "ERROR" /var/log/app/error.log | cut -d' ' -f5 | sort | uniq -c | sort -rn

相关文档

• 常见故障排查
• 疑难案例库
• API 文档