错误码

新版通过 HTTP 状态码与稳定的英文 code 判断接口结果，message 仅用于阅读，request_id 用于追踪。 适用新版认证协议。

此页为新版文档预览。相同业务码可能因接口返回不同 HTTP 状态，例如开票结果未知为 502，查验幂等执行结果未知为 503。请同时保留 HTTP 状态、code 和 request_id。查验中心还可能返回以下稳定业务码：

AUTHZ_DENIED、TAXPAYER_NOT_AUTHORIZED（403）；TAXPAYER_NOT_FOUND、CHANNEL_NOT_CONFIGURED（404）；CHANNEL_DISABLED（403）；CHANNEL_UNAVAILABLE、CHECK_FAILED（502）；CHANNEL_TIMEOUT（504）；VALIDATION_ERROR（400）。部分发票失败会出现在 data.results[].response 中，不能仅凭外层 OK 判定发票真伪。

HTTP 200OK

成功；查无数据、查验结论等正常业务结果见 data

HTTP 202OK

已受理；data.status 为 PROCESSING

HTTP 400REQUEST_INVALID

请求头、业务参数或 JSON 格式无效

HTTP 400HTTPS_REQUIRED

必须通过 HTTPS 调用

HTTP 401AUTH_SIGNATURE_INVALID

签名无效；检查请求字节、路径和签名头

HTTP 401AUTH_TIMESTAMP_INVALID

时间戳格式无效或超出允许窗口；校准时钟

HTTP 401AUTH_REPLAY_DETECTED

随机数已使用；重试时生成新的随机数和签名

HTTP 401AUTH_INVALID_CREDENTIAL

凭证无效、已停用或所属企业不可用

HTTP 401AUTH_CREDENTIAL_ROTATION_REQUIRED

原凭证尚未支持签名，需创建新凭证或重新生成 Secret

HTTP 403PERMISSION_DENIED

企业、税号或业务能力未授权

HTTP 403BUSINESS_NOT_ELIGIBLE

当前主体不具备该业务办理资格

HTTP 404RESOURCE_NOT_FOUND

资源不存在或不可访问

HTTP 409CONNECTION_REQUIRED

税局连接不可用或业务当前无法处理

HTTP 409IDEMPOTENCY_CONFLICT

同一幂等键被用于不同请求；核对业务标识

HTTP 405METHOD_NOT_ALLOWED

该路径不支持所用 HTTP 方法

HTTP 413REQUEST_TOO_LARGE

请求体超过接口允许上限

HTTP 409IDEMPOTENCY_IN_PROGRESS

同一查验业务请求正在处理中；稍后用原幂等键和新签名重试，不要更换幂等键

HTTP 503IDEMPOTENCY_SERVICE_UNAVAILABLE

幂等保护暂不可用；请求不会绕过保护执行

HTTP 415UNSUPPORTED_MEDIA_TYPE

请求需为未压缩的 application/json UTF-8

HTTP 500INTERNAL_ERROR

平台内部错误；凭 request_id 联系平台

HTTP 502UPSTREAM_ERROR

上游处理失败；写操作先核对业务状态

HTTP 502BUSINESS_RESULT_UNKNOWN

开票等业务结果未知；先核实，禁止盲目重复提交

HTTP 503BUSINESS_RESULT_UNKNOWN

查验结果无法确认，保留原幂等键及请求号联系平台核实，禁止换键自动重试

HTTP 503OPENAPI_DISABLED

新版入口尚未启用或暂时关闭；旧版入口不受该开关影响

HTTP 503AUTH_SERVICE_UNAVAILABLE

统一认证服务不可用；不会跳过认证或自动回退

旧版业务码（保留）

以下仅适用于旧版税务接口。业务错误码在解密后的 Data.returncode 字段中返回，具体文案见 returnmsg。

returncode含义
00成功
01参数校验异常
03拒绝处理（含登录态失效，需引导重新建立连接）
04查无数据
09系统处理异常
10数据处理中，建议稍后重试
11当前企业无资格办理此业务（含接口尚未上线的情形）
99系统级异常

注：returncode=02 未使用；未列出的编号当前均未定义。