错误处理 & 错误编码

错误处理

本节描述了 API 中错误是如何表示的、使用了哪些 HTTP 状态码，以及如何解释业务级别的错误代码。

该设计遵循计费/发票平台等公共 API 所使用的常见模式（HTTP 状态码用于粗略的错误分类，机器可读的 code 用于业务细节，人类可读的 message 用于开发者）。

1. 错误对象模型

所有非 2xx 响应都在响应正文中返回一个标准的错误对象：

{
  "error": {
    "code": "string",
    "message": "string",
    "param": "string",
    "details": { },
    "request_id": "string",
    "trace_id": "string"
  }
}

字段

error.code (string, required)
机器可读的错误代码，供客户端用于程序化处理
（例如 invoice_not_found、info_mismatch、missing_invoice_type）。

error.message (string, required)
人类可读的、对开发者友好的错误描述，
适合用于日志或用户界面（翻译后）。

error.param (string, optional)
当错误是字段特定时，与错误相关的参数名称（例如 invoice_type、invoice_number、tax_no）。

error.details (object, optional)
关于错误的结构化附加信息。
例如，重试标志或额外的业务细节：

"details": {     
    "retryable": true,
    "retry_after": 60
}

error.request_id (string, required)
请求的唯一标识符，成功响应中也会返回。
在联系支持人员或搜索日志时使用此字段。

error.trace_id (string, optional)
分布式追踪标识符，用于跨服务追踪请求链路。

重要提示：
成功的响应绝不能包含 error 字段（甚至 error: null 也不行）。
错误响应始终遵循此结构，无论端点如何。
param、details、trace_id 字段为空时不返回（使用 @JsonInclude(NON_NULL)）。

2. HTTP 状态码

API 使用标准的 HTTP 状态码来指示请求是成功还是失败以及原因。

2.1 成功代码

200 OK
请求成功，查验成功并返回发票详细信息。

201 Created
成功创建了一个新资源（例如订单、发票、电子税局账户）。

2.2 客户端错误代码

400 Bad Request
请求参数缺失、格式错误或不合法。
例如：发票代码格式错误、发票类型不支持、查询发票不规范。

401 Unauthorized
身份验证失败（访问令牌无效或已过期）。

403 Forbidden
调用者已通过身份验证，但没有执行该操作的权限
（例如，ISV 无法访问指定的租户或公司）。

404 Not Found
请求的路径/资源不存在。

409 Conflict
资源的当前状态与请求的操作冲突，一般是幂等性冲突。

422 Unprocessable Entity
请求在语法上有效，但因不满足业务规则而无法处理。
这尤其用于业务错误，例如：

发票不存在、发票信息不一致

超过当天查验次数、超过最大查验量

发票超出可查验期限、票种不支持

429 Too Many Requests
请求过于频繁，已被限流。
例如：查验请求过于频繁、查验服务暂时不可用。

2.3 服务器错误代码

500 Internal Server Error
服务器端发生了意外错误（例如查验通道鉴权失败）。

503 Service Unavailable
服务暂时不可用（例如查验异常、该地区服务暂停）。

3. 全局错误代码

本节列出了可能出现在多个端点中的常用 error.code 值。

3.1 一般错误

code	HTTP	Description
`invalid_param`	400	参数缺失或格式错误
`unauthorized`	401	未获取到鉴权信息或令牌无效
`permission_denied`	403	调用者没有权限
`not_found`	404	资源未找到
`conflict`	409	资源状态冲突
`business_error`	422	一般业务错误（详见 message/details）
`internal_error`	500	意外的内部服务器错误

3.2 多租户 / ISV 错误

code	HTTP	Description
`tenant_not_found`	404	租户不存在或对 ISV 不可见
`tenant_not_belong_to_isv`	403	租户与当前的 ISV 不关联
`company_not_found`	404	公司不存在或对 ISV 不可见

4. 订单错误代码

针对订单相关端点（例如 /isv/orders）。

code	HTTP	Description
`order_not_found`	404	订单不存在
`order_conflict`	409	订单号已存在
`order_status_not_allowed`	422	当前订单状态不允许此操作（例如终止或开票）
`order_already_closed`	409	订单已关闭，无法重复关闭
`order_update_failed`	422	订单更新失败
`order_not_activated`	422	该企业订单未激活

示例 – 重复的订单号：

{
  "error": {
    "code": "order_conflict",
    "message": "订单号已存在",
    "param": "order_no",
    "request_id": "req_1701937730123_44444444",
    "trace_id": "trace_abc123"
  }
}

5. 电子税局错误代码

这些代码特定于电子税局账户和发票开具。

5.1 电子税局账户

code	HTTP	Description
`etax_account_invalid`	422	电子税局账号或密码错误
`etax_account_already_exists`	422	该电子税局账号已存在
`account_not_found`	404	未找到指定的电子税局账号
`password_mismatch`	422	密码不正确
`max_accounts_exceeded`	422	每个企业最多只能维护账号数量限制

5.2 电子税局开票

code	HTTP	Description
`etax_api_failed`	422	调用电子税局开票接口失败
`etax_api_error`	422	电子税局API调用失败
`etax_param_invalid`	422	开票参数验证失败

示例 – 电子税局验证失败：

{
  "error": {
    "code": "etax_account_invalid",
    "message": "电子税局账号或密码错误",
    "param": "etax_account/etax_password",
    "details": {
      "provider_code": "101",
      "provider_message": "密码错误"
    },
    "request_id": "req_1701937730123_55555555",
    "trace_id": "trace_def456"
  }
}

6. 异步操作与业务失败

有些操作（例如发票开具）可能是异步的：

创建端点（例如 POST /isv/invoices）返回 201 Created 时，表示作业已被接受，而不是 ETAX 已完成处理。

然后发票资源会公开一个 status 字段，例如：

* PENDING / PROCESSING
* SUCCEEDED
* FAILED

在此模型中：

HTTP 2xx 表示请求已被接受且作业已创建。

业务成功/失败由资源状态表示，而不是 HTTP 状态码。

当 status = "FAILED" 时，资源包含失败元数据：

{
  "invoice_id": "inv_456",
  "status": "FAILED",
  "fail_code": "etax_issue_failed",
  "fail_message": "ETAX response: buyer taxpayer number is invalid",
  "fail_time": "2025-12-07T12:11:00Z"
}

经验法则
同步业务失败 → 使用 HTTP 422 + error 对象。
异步业务失败 → 使用资源上的 status = FAILED 和失败字段。

7. 发票查验响应设计

发票查验遵循严格的 Resource-Oriented 设计。

设计原则：
查验成功且发票有效 → 返回 200 OK + 发票详细信息
查验失败（任何原因） → 返回对应的 4xx/5xx 状态码 + error 对象
没有中间状态：不存在"技术成功但业务失败"的情况

HTTP 状态码使用规范

参考：2.2 客户端 / 业务错误代码

7.1 查验成功响应（200 OK）

查验成功时，返回 200 OK + 发票详细信息（不包含 result_code 字段）。

7.2 查验错误代码

以下错误用于查验失败的各种场景，返回对应的 HTTP 状态码 + error 对象。

7.2.1 查验业务错误

code	HTTP	Description
`invoice_not_found`	422	所查发票不存在
`info_mismatch`	422	查验成功但发票信息不一致
`invoice_not_belong`	422	此发票非本单位开具或取得
`invoice_not_standard`	400	查询发票不规范

7.2.2 查验参数校验错误

code	HTTP	Description
`missing_invoice_type`	400	发票类型不能为空
`invalid_invoice_type`	400	不支持的发票类型
`missing_invoice_number`	400	发票号码不能为空
`invalid_invoice_number`	400	发票号码格式错误
`missing_invoice_code`	400	发票代码不能为空
`invalid_invoice_code`	400	发票代码格式错误，应为10-12位数字
`missing_issue_date`	400	开票日期不能为空
`invalid_issue_date`	400	开票日期格式错误，应为YYYY-MM-DD
`missing_verification_code`	400	校验码不能为空
`invalid_verification_code`	400	校验码格式错误，应为6位字母或数字
`missing_invoice_amount`	400	金额不能为空
`invalid_invoice_amount`	400	金额格式错误
`invalid_param`	400	请求参数不合法（含发票代码格式错误、发票类型不支持）
`time_range_exceeded`	422	仅可查验最近一年内开具的财政电子票据
`type_not_supported`	422	暂不支持该票种查验
`today_invoice_limit`	422	当日开具发票暂时无法查验，请次日再试

7.2.3 查验限流与配额错误

code	HTTP	Description
`daily_limit_exceeded`	422	超过该张票当天查验次数
`max_limit_exceeded`	422	已超过最大查验量
`request_too_frequent`	429	当前发票正在查验中，请勿频繁请求

7.2.4 查验服务错误

code	HTTP	Description
`service_unavailable`	429	查验服务暂时不可用，请稍后重试
`check_exception`	503	查验异常，请稍后重试
`region_suspended`	503	该地区服务暂停
`auth_failed`	500	查验通道鉴权失败（内部错误）
`token_expired`	401	访问令牌已过期（内部错误）

7.3 错误响应示例

超过查验次数（422）：

{
  "error": {
    "code": "daily_limit_exceeded",
    "message": "超过该张票当天查验次数",
    "request_id": "req_1701937730123_77777777",
    "trace_id": "trace_ghi789"
  }
}

参数校验失败（400）：

{
  "error": {
    "code": "missing_invoice_number",
    "message": "发票号码不能为空",
    "param": "invoice_number",
    "request_id": "req_1701937730123_88888888",
    "trace_id": "trace_jkl012"
  }
}

发票不存在（422）：

{
  "error": {
    "code": "invoice_not_found",
    "message": "所查发票不存在",
    "request_id": "req_1701937730123_99999999",
    "trace_id": "trace_mno345"
  }
}

8. 客户端集成指南

在与 API 集成时，客户端应：

首先检查 HTTP 状态码

2xx → 视为技术成功（然后检查异步流程的业务状态）。

非 2xx → 解析 error 对象。

使用 error.code 进行程序化处理

实现基于 error.code 的 switch/映射来驱动业务逻辑。

不要依赖匹配 message 文本。

记录 request_id 和 error

始终记录 request_id、error.code 和 error.message 以用于可观察性和支持。

使用 details 进行高级处理

例如，使用 details.retryable 或特定的代码来决定是否重试。

9. 服务公共错误代码

Code	Http	Description
1300	401	[服务网关]请求TOKEN不能为空
1301	401	[服务网关]非法的TOKEN,或者TOKEN已经失效
0013	400	[服务网关]数据解密异常
0014	400	[服务网关]解密未获得字符异常
0015	400	[服务网关]未支持的加密模式
0011	500	[服务网关]网络繁忙

错误处理#

1. 错误对象模型#

字段#

2. HTTP 状态码#

2.1 成功代码#

2.2 客户端错误代码#

2.3 服务器错误代码#

3. 全局错误代码#

3.1 一般错误#

3.2 多租户 / ISV 错误#

4. 订单错误代码#

5. 电子税局错误代码#

5.1 电子税局账户#

5.2 电子税局开票#

6. 异步操作与业务失败#

7. 发票查验响应设计#

HTTP 状态码使用规范#

7.1 查验成功响应（200 OK）#

7.2 查验错误代码#

7.2.1 查验业务错误#

7.2.2 查验参数校验错误#

7.2.3 查验限流与配额错误#

7.2.4 查验服务错误#

7.3 错误响应示例#

8. 客户端集成指南#

9. 服务公共错误代码#