错误码说明

概述

环能聚合API使用统一的错误码规范，通过返回的错误码可以快速定位和解决接口调用过程中遇到的问题。错误码分为系统级错误码和业务级错误码两大类，每个错误码都包含详细的错误信息和解决建议。

错误码结构

格式： 数字编码 + 错误信息
范围： 1000-9999
分类： 系统级(1000-1999)、业务级(2000-9999)
语言： 中文错误信息

系统级错误码 (1000-1999)

错误码 错误信息 说明 解决建议
1000 系统繁忙 服务器临时过载 稍后重试或联系技术支持
1001 服务不可用 服务暂时不可用 检查服务状态，稍后重试
1002 接口不存在 请求的接口不存在 检查接口URL是否正确
1003 请求方法不支持 HTTP方法不被允许 使用正确的HTTP方法
1004 请求超时 请求处理超时 检查网络连接，减少请求数据量
1005 系统错误 内部系统异常 联系技术支持
1006 数据库错误 数据库操作失败 联系技术支持
1007 缓存错误 缓存操作失败 联系技术支持
1008 网络错误 网络连接异常 检查网络连接
1009 配置错误 系统配置异常 联系技术支持

认证授权错误码 (1100-1199)

错误码 错误信息 说明 解决建议
1100 认证失败 身份认证失败 检查AppKey和签名是否正确
1101 签名错误 签名验证失败 检查签名算法和参数排序
1102 时间戳过期 请求时间戳已过期 同步系统时间，重新生成时间戳
1103 AppKey无效 AppKey不存在或已禁用 检查AppKey是否正确，联系管理员
1104 权限不足 无访问该接口的权限 申请相应接口权限
1105 IP受限 IP地址不在白名单内 配置IP白名单
1106 访问频率超限 超过接口调用频率限制 降低调用频率，申请提升配额
1107 Token无效 访问令牌无效或已过期 重新获取访问令牌

参数验证错误码 (1200-1299)

错误码 错误信息 说明 解决建议
1200 参数缺失 缺少必需参数 检查并补充必需参数
1201 参数格式错误 参数格式不符合要求 检查参数格式，参考接口文档
1202 参数值无效 参数值超出允许范围 检查参数值范围
1203 JSON格式错误 请求JSON格式不正确 检查JSON格式，使用JSON验证工具
1204 编码格式错误 字符编码格式错误 使用UTF-8编码
1205 数据过长 参数值超过最大长度 缩短参数值长度
1206 数据过短 参数值小于最小长度 增加参数值长度
1207 日期格式错误 日期格式不符合要求 使用标准日期格式(YYYY-MM-DD)
1208 数值格式错误 数值格式不正确 检查数值格式
1209 布尔值格式错误 布尔值格式不正确 使用true/false

业务级错误码 (2000-9999)

用户相关错误码 (2000-2099)

错误码 错误信息 说明 解决建议
2000 用户不存在 指定的用户不存在 检查用户ID是否正确
2001 用户已存在 用户已注册 使用其他用户名或找回密码
2002 用户状态异常 用户账号被禁用或锁定 联系管理员解锁账号
2003 密码错误 登录密码不正确 检查密码或重置密码
2004 用户未激活 用户账号未激活 完成账号激活流程

企业相关错误码 (2100-2199)

错误码 错误信息 说明 解决建议
2100 企业不存在 指定的企业信息不存在 检查企业ID或统一社会信用代码
2101 企业已存在 企业已注册 使用现有企业信息
2102 企业信息不完整 企业注册信息不完整 补充完整企业信息
2103 企业状态异常 企业状态异常 联系管理员处理
2104 企业认证失败 企业实名认证失败 重新提交认证材料

税务相关错误码 (2200-2299)

错误码 错误信息 说明 解决建议
2200 税务登记号无效 税务登记号格式错误或不存在 检查税务登记号是否正确
2201 税务机关编码错误 税务机关编码无效 检查税务机关编码
2202 申报期已过 已超过申报期限 联系税务机关处理
2203 申报数据错误 申报数据格式或内容错误 检查申报数据格式
2204 税种不存在 指定的税种代码无效 检查税种代码

数据相关错误码 (2300-2399)

错误码 错误信息 说明 解决建议
2300 数据不存在 请求的数据不存在 检查查询条件
2301 数据已存在 数据已存在，不能重复创建 使用更新接口或查询现有数据
2302 数据已过期 数据版本已过期 获取最新数据版本
2303 数据被锁定 数据正在被处理 稍后重试
2304 数据格式错误 数据格式不符合要求 检查数据格式

错误处理最佳实践

错误处理流程

try {
    // 调用API
    response = api.call(params);
} catch (ApiException e) {
    switch (e.getCode()) {
        case 1100: // 认证失败
            refreshCredentials();
            break;
        case 1200: // 参数缺失
            validateParameters(params);
            break;
        case 1000: // 系统繁忙
            retryWithBackoff();
            break;
        default:
            logError(e);
            notifyAdmin(e);
    }
}

重试策略

错误码 是否可重试 重试间隔 最大重试次数
1000 是 指数退避(1s, 2s, 4s...) 3次
1001 否 - -
1100 否 - -
1200 否 - -
2300 否 - -

调试工具

错误调试建议

1. 记录完整日志

记录请求参数、响应数据、错误码、时间戳等完整信息，便于问题定位。

2. 使用测试环境

在测试环境中重现问题，避免影响生产数据。

3. 检查网络连接

确认网络连接正常，排除网络因素导致的错误。

4. 验证参数格式

使用参数验证工具检查参数格式是否符合要求。

5. 查看官方文档

对照官方文档检查接口使用是否正确。

获取技术支持

联系方式

技术支持邮箱

support@huaneng.com

技术支持电话

400-123-4567 (工作日 9:00-18:00)

工单系统

登录开发者中心提交技术支持工单