数电发票接口报错定位：先分层，再看错误码，最后才谈重试

数电开票的报错信息大多长得很像——“操作失败”“额度不足”，但落到处置动作上可能是找税务局、改税率、重新登录，或者只是等 30 秒重试。把错误先归到正确的层，比记住错误码本身更重要。

本文整理自易宝开放平台数电发票服务接口文档、微信支付电子发票冲红接口文档、第三方开票平台错误码表（piaozone open-standard）以及票点云技术博客的分类归纳。文中标注了各条口径的出处；除标注为“文档口径”的内容外，其余未逐条实测，接入时请以对接通道的最新文档为准。

一、先分层：四类错误的处置动作完全不同

这套分层来自票点云技术博客的归纳，不是官方分类，但用于排障时很好用。

A. 税局侧额度类——找主管税务机关或等待额度调整，改代码无效。

• 额度不足 / 可用额度为 0
• 总额度暂不可调整（需确认流程中）

B. 请求参数类——改代码或改配置，重试无效。

• 不合法税率
• 税收分类编码有误
• 特定业务标签必填项缺失
• 抬头 / 税号格式不合法

C. 鉴权类——回到登录链处理，与报文内容无关。

• 未登录 / token 失效 / 权限不足

D. 平台侧瞬时类——重试 + 幂等，通常不需要改任何东西。

• 网关超时 / 限流 / 服务暂不可用

判断顺序建议从 D 往 A 排除：先确认是不是瞬时抖动（看请求号是否幂等、重试一次即可验证），再看会话态是否还在有效期内，最后才怀疑参数和额度。反过来做，很容易在“额度不足”上耗掉半天，实际是税率和税收分类编码对不上。

数电发票要求商品对应正确的税收分类编码，且编码与适用税率要对应。常见触发场景：编码选错（货物类商品选了服务类编码）、税率与编码不匹配、特定业务标签（建筑服务、成品油、报废产品收购等）的附加字段漏填。

二、会话态：最容易被忽略的一层

（以下为易宝开放平台文档口径）

数电开票不是“有密钥就能开”，要先过一条会话链：服务开通 → 开票员登录 → 实人认证。这三步各有各的中间态和超时。

服务开通激活接口

• 1211：服务开通中，等 30 分钟后再次调用可拿终态
• 1017：需继续调短信验证码接口
• 0000：激活成功

开票员登录

• 1209：登录中，稍后重试
• 1107：只有未登录才能调用该接口登录——说明当前已登录，改调登录状态查询
• 传入短信验证码后返回 1203（查询中），不换请求号轮询直至终态，预计 20s 内

实人认证

• 获取人脸核验二维码有效期 5 分钟，5 分钟内必须调“获取人脸核验结果”
• 超时返回 1112「人脸核验二维码已过期，请重新获取」
• 返回 1203 表示查询中，继续用同一请求号

业务错误码（易宝文档口径）

• 1103 未查询到数电账号
• 1105 该数电账号暂未登录（调登录接口）
• 1300 当前操作需登录电子税局
• 2001 发票服务未开通
• 2002 开通中（等待后查）
• 2005 已停用
• 2006 已到期
• 3001 发票服务未授权（先激活授权）
• 3005 激活中
• 1003 商编税号关系未维护
• 1004 销方信息未维护
• 1016 企业信息已注册（改信息要用修改接口，不能重复注册）
• 新增 / 修改开票员返回 1017 时，需调短信验证码接口，operationType 传 addEtaxAccount

这条链的工程含义很直接：会话态有状态、有超时、还包含人工扫码环节（人脸核验），不能塞进同步接口里一边收单一边开票。合理做法是把“开票前置健康度”拆成独立任务，定时跑登录状态与授权状态检查，把 1105、2002、3005 这类可恢复状态提前消化掉，而不是等到用户点开票时才暴露。

三、受理 ≠ 开票成功

多数通道的开票接口是异步的：调用返回成功只代表请求被受理，必须再调“开具结果查询”拿终态（易宝为 issue-invoice / query-invoice）。

红冲同理：快速红冲接口调完要查结果；返回「查询红票数电发票号码失败」时需再次查询。

微信支付电子发票冲红接口（文档口径）：成功返回仅代表冲红请求已受理，完成时会回调通知，也可调用“查询电子发票”确认。红字发票开具失败时，可用相同的 fapiao_information.fapiao_id 重填冲红原因重试，每次重试间隔 5 分钟。

微信冲红常见错误码：

INVALID_REQUEST 的两种含义值得单独拆开：前者是传输层问题（方法、路径、请求头不合 APIv3 规范），后者是业务规则拒绝。两者 HTTP 码相同，只能靠日志里的具体报文区分。

冲红原因枚举（数电模式）：ISSUE_ERROR 开票有误、SALES_RETURN 销货退回、SERVICE_SUSPENTION 服务中止（原文拼写如此）、SALES_DISCOUNT 销售折让。

四、明细行校验

以下为第三方通道错误码示例，具体口径以各家文档为准：

• 10127 单据编号重复
• 10157 税率不合法 / 10158 税额不合法
• 10160 税收分类编码与商品编码不能同时为空
• 10161 税收分类编码为汇总项或不存在
• 10156 金额为空或为 0 时，单价和数量不能同时为空或 0
• 10151 开红票时明细金额不能大于 0，且不能有折扣行；蓝票明细行金额不能小于 0
• 10108 蓝票已作废 / 已红冲不能再红冲；红字信息表未提交或审核失败
• 10131 收票手机和收票邮箱不能同时为空

折扣行规则（易宝文档口径）：第一行不能是折扣行；折扣行必须紧跟被折扣行；一条被折扣行仅能有一条折扣行；折扣行的商品编码、名称、税率须与被折扣行一致；折扣行不能传单价、数量、单位、规格型号。

10157 / 10158 这类错误重试一百次结果都一样，属于 B 类参数问题；10127 单据编号重复则是幂等键命中了，正确做法是去查结果而不是换号重提。

五、时效与幂等

• 开票二维码有效期 30 天；作废已被扫码的二维码会报「开票二维码已被扫码申请开票。无法作废」。
• 税额 / 金额算错导致的红冲，是最贵的一类返工：红冲需要人工或审核介入，且蓝票已红冲后不能再红冲。金额计算放在提交前做一次独立校验，成本远低于事后红冲。
• 幂等：以单据编号（fpqqlsh / 业务单号）为幂等键，重复提交应返回上一次结果，而不是重复开票。

把这几条串起来，排障路径基本是固定的：先看错误码归属哪一层 → 瞬时类才谈重试 → 重试必须带幂等键 → 非瞬时类回到会话态或明细参数上找原因。