错误码说明

所有业务接口的响应体均包含 code 字段，用于表示本次调用的业务执行结果。

{
    "code": 0,
    "message": "success",
    "data": { ... },
    "traceId": "xxxx-xxxx-xxxx-xxxx"
}

字段	类型	说明
code	Integer	业务状态码；`0` 表示成功，非 `0` 表示失败，具体含义见下表
message	String	状态描述文本，失败时包含具体原因
traceId	String	链路追踪 ID，排查问题时请提供此值

💡

提示：HTTP 状态码与业务状态码相互独立。接口返回 HTTP 200 并不代表业务成功，需以响应体中的 code 字段为准。

成功码

code	说明
0	成功

税局异常 `1000 – 1999`

税局侧返回的异常，通常由税局系统不稳定、接口变更或业务状态不满足条件引起。

网络异常 `10xx`

code	枚举名	说明	建议处理方式
1001	Tax_NetworkError	税局网络异常（网关错误、网关超时等）	稍后重试

服务异常 `11xx`

code	枚举名	说明	建议处理方式
1101	Tax_ServiceError	税局服务器内部异常	稍后重试；若持续出现请联系柠檬云技术支持
1102	Tax_TimeOut	税局响应超时	稍后重试
1103	Tax_Declaring	申报已提交，结果处理中（各税种通用）	轮询查询申报状态，等待税局处理完成

接口异常 `12xx`

code	枚举名	说明	建议处理方式
1201	Tax_ApiError	税局业务接口调用失败	查看 `message` 字段获取税局原始错误描述
1202	Tax_PayError	缴税异常（余额不足等）	检查缴税账户余额
1203	Tax_PaySfError	缴税三方协议异常	确认三方协议是否有效
1204	Tax_PayReservedError	待缴税列表中存在已预约的缴费信息	检查是否存在重复预约
1205	Tax_PayNoDataError	待缴税列表中无数据	确认当前税款所属期是否存在应缴税款
1215	Tax_PayerInfoError	纳税人基本信息异常（如企业状态为注销）	确认企业税务状态是否正常

数据不存在 `13xx`

code	枚举名	说明	建议处理方式
1301	Tax_InExistence	未在税局找到指定信息	确认查询条件（税款所属期、发票号码等）是否正确

客户端异常 `2000 – 2999`

由调用方参数、权限或操作时序问题引起，通常需要调用方修正请求后重试。

认证与会话

code	枚举名	说明	建议处理方式
2001	Client_Unauthentication	身份认证失败（账号/密码/验证码错误等）	检查登录凭证；查看 `message` 获取税局原始提示
2006	Client_SessionExpired	税局会话已失效	重新发起登录任务，获取新会话后重试

频率与权限

code	枚举名	说明	建议处理方式
2002	Client_FrequencyFast	操作过于频繁（验证码发送次数超限等）	降低调用频率，等待限制解除后重试
2003	Client_PermissionDenied	当前企业无该功能访问权限	确认纳税人资格与功能授权
2015	Client_IssuePermissionDenied_NeedScanFace	需先完成人脸认证扫码才能开票	引导用户完成人脸认证流程
2016	Client_IssuePermissionDenied	开票权限不足	确认开票账号权限；查看 `message` 获取详细原因
2018	Client_ReportPermissionDenied	无办税权限	在电子税务局为当前账号分配相应权限
2019	Client_NoCompanyPermission	自然人税局账号无该公司权限	检查账号与企业的绑定关系

认证等级 `202x`

code	枚举名	说明	建议处理方式
2020	Client_LowAuthenticationLevel	当前账号认证等级过低	引导用户在电子税务局提升认证等级
2021	Client_AuthTooFrequent	认证操作过于频繁，暂时受限	稍后重试
2022	Client_AuthLimitExceeded	认证次数超出上限，账号已被临时锁定	等待锁定解除或通过"忘记密码"重置

用户操作

code	枚举名	说明	建议处理方式
2004	Client_UserOperation	用户操作不符合业务规则（如重复申报、蓝票不可红冲等）	查看 `message` 获取税局原始提示，引导用户按规则操作

参数与业务校验

code	枚举名	说明	建议处理方式
2005	Client_ParameterError	通用参数错误	检查请求参数格式与取值范围
2009	Client_ParameterError_TaxRateError	发票明细税率不合法	检查各行商品税率，使用税局支持的合法税率值
2010	Client_ParameterError_TaxAmountError	开具金额或税额有误	检查含税金额、税额计算精度；首次开票注意单份金额上限
2011	Client_ParameterError_UnitError	商品计量单位不合法	使用税局规定的标准计量单位枚举值
2012	Client_ParameterError_ExistCalculationError	明细行金额存在计算误差	校验金额精度，误差不得超过税局允许范围
2013	Client_ParameterError_UnsupportedBusinessMode	不支持的业务模式（商品编码与开票类型不匹配）	确认商品税收分类编码与发票类型的对应关系
2014	Client_ParameterError_USCCERROR	购买方纳税人识别号长度或格式不符合规范	检查购买方税号位数与格式
2017	Client_ParameterError_QuotaExceeded	发票额度不足	联系主管税务机关申请调整发票授信额度

服务端异常 `3000 – 3999`

由柠檬云服务内部处理异常引起，通常可重试。

code	枚举名	说明	建议处理方式
3001	Service_HandleDataError	数据操作失败（数据库写入、数据同步等）	稍后重试；若持续出现请联系技术支持
3002	Service_HandleFileError	文件操作失败（下载、解析、上传等）	稍后重试
3003	Service_InitializationError	初始化失败（浏览器创建、数据库连接等）	稍后重试
3005	Service_TimeOut	任务执行超时	稍后重试；异步任务可重新发起
3006	Service_ValidationError	服务端校验不通过（表单数据、验证码失效等）	查看 `message` 获取具体校验失败原因
3007	Service_LoadingPageError	税局页面加载或元素定位异常	稍后重试；若持续出现可能为税局页面变更，请联系技术支持
3008	LoginFailed_CompanyInQueue	该企业当前有排队中的任务，无法重复登录	等待当前排队任务完成后再发起登录
3997	UnknownError	未知错误，可尝试重试	重试一次；若仍失败请携带 `traceId` 联系技术支持
3998	DefaultNoRetry	不可恢复的错误，重试无效	查看 `message`，按提示处理后重新请求
3999	DefaultRetry	可重试的通用错误	稍后重试最多两次

接口层异常码 `9000 – 9999`

由 API 网关或服务框架层抛出，与业务 code 字段含义相同，均通过响应体 code 返回。

code	枚举名	说明	建议处理方式
9001	Exception_AlreadyExists	当前企业已有正在执行的同类任务	等待已有任务结束后再发起新任务
9002	Exception_Internal	服务内部错误	携带 `traceId` 联系柠檬云技术支持
9003	Exception_NotFound	指定资源不存在（任务、企业数据等）	确认传入的任务 ID（`taskID` 或 `taskId`，以接口 schema 为准）、`uscc` 等参数是否正确
9004	Exception_Unavailable	服务不可用（当前地区或业务类型暂不支持）	查看 `message` 确认具体限制；联系商务确认覆盖范围
9005	Exception_UserLoginExpired	用户登录已过期	重新发起登录任务后重试
9006	Exception_ResourceExhausted	请求频率超限	降低调用频率，按 `message` 中提示的等待时间后重试
9007	Exception_AlreadyExistsLogin	当前账号已有进行中的登录任务	等待已有登录任务完成后再发起
9008	Exception_DeadlineExceeded	后端服务调用超时（gRPC 超时）	稍后重试
9999	Exception_Unknown	未知异常	携带 `traceId` 联系柠檬云技术支持

通用处理建议

错误范围	处理策略
`1001` / `1101` / `1102`	税局侧问题，建议间隔 3–5 秒后最多重试 3 次
`2001` / `2006`	认证/会话问题，需重新发起登录任务，不应盲目重试
`2002` / `9006`	频率限制，遵守 `message` 中的等待时间后重试
`2005` – `2017`	参数问题，需修正请求参数后重试，不应原样重试
`3005` / `3999`	可重试错误，建议间隔后重试，最多重试两次
`3998`	不可重试，需根据 `message` 人工处理后重新请求
`9001` / `9007`	并发冲突，等待已有任务完成后再发起
`9002` / `9999`	内部/未知错误，请携带 `traceId` 联系技术支持

成功码#

税局异常 1000 – 1999#

网络异常 10xx#

服务异常 11xx#

接口异常 12xx#

数据不存在 13xx#

客户端异常 2000 – 2999#

认证与会话#

频率与权限#

认证等级 202x#

用户操作#

参数与业务校验#

服务端异常 3000 – 3999#

接口层异常码 9000 – 9999#

通用处理建议#

成功码