参考
错误码
TF Fiscal Open API 错误码合并参考，按层与领域分组，附 HTTP 状态、场景与处置建议。
错误形状
错误按产出层分三种形状，见通用约定：
| 层 | HTTP | 形状 | 码字段 |
|---|---|---|---|
| 平台网关（鉴权、订阅、限流、文件下载链接） | 401 / 403 / 404 / 429 / 503 | 平台信封 {success, errorType, code, message} | code（整数） |
| 开票主体、NF-e、CT-e、DC-e、Webhook 注册 | 400 / 404 | 数组 [{codigo, mensagem}]，每个问题一条 | codigo（字符串） |
| NF-e 验证与身份核验 | 400 / 422 / 428 / 451 / 500 / 503 | 裸对象 {code, message} | code（整数） |
message 随 Language / Accept-Language 请求头本地化（默认葡语）。请按码分支，不要按文案分支。数组形状里 GW001、CER0005、NFe0001、CTe0001、DCe0001 与 DCe0000x 沿用字母数字原码；其余 codigo 为平台错误码数字串。
各领域码段：
| 码段 | 领域 |
|---|---|
| 10001xxx | 请求校验与平台异常 |
| 10003xxx | 开票主体与证书 |
| 10004xxx | NF-e 开票、作废与更正函 |
| 10005xxx | 税务引擎 |
| 10009xxx | 开放平台（鉴权、订阅、限流、webhook、下载链接） |
| 10013xxx | 文件下载 |
| 10015xxx | NF-e 验证 |
| 10016xxx | 身份核验（CNPJ / CPF） |
| 10017xxx | CT-e |
| 10019xxx | DC-e |
网关：鉴权与授权
平台信封形状，在请求到达接口前产出。401 与 403 属配置错误，不修复就重试没有意义，还可能触发限流。签名方案见认证与签名。
| HTTP | code | 含义 | 处置 |
|---|---|---|---|
| 401 | 10009000 | 缺少签名请求头（token / sign / timestamp） | 每次请求带全三个头 |
| 401 | 10009001 | 时间戳非法或时钟偏差超 ±300 秒 | 校准时钟（NTP）；每次请求重新生成时间戳，勿复用 |
| 401 | 10009002 | token 无效 | 核对 app_secret；如已轮换请更新配置 |
| 401 | 10009003 | 签名不匹配 | 重新推导签名；见认证与签名的核对清单 |
| 403 | 10009004 | 应用已停用 | 联系平台 |
| 403 | 10009015 | 应用未生效（待审批或已驳回） | 等待审批 / 联系平台 |
| 403 | 10009014 | 集成商账户已停用 | 联系平台 |
| 403 | 10009005 | 接口未订阅 | 为所调端点申请订阅 |
| 429 | 10009006 | 超出限流额度 | 退避重试（初始 1 秒，倍增至 30 秒上限，加抖动）；限流按应用与接口组两级实施 |
下载链接（linkDanfe、linkDownloadXml、linkDacce、nfeLinkXml、cteLinkDacte、dceLinkDace 等）是不带签名头的 GET 请求；失败以 HTTP 状态 + 平台信封返回，见文件下载：
| HTTP | code | 含义 | 处置 |
|---|---|---|---|
| 401 | 10009035 | 下载链接无效（路径被改、令牌挪用或签名不符） | 使用查询接口原样返回的链接 |
| 401 | 10009036 | 下载链接已过期 | 重新调用查询接口获取新链接 |
| 503 | 10009037 | 文件尚未生成（渲染服务繁忙） | 按 Retry-After 稍后重试同一链接 |
| 404 | 10013011 | 下载的文件不存在 | 核对链接来源 |
| 429 | 10013016 | 回调链接的单 IP 下载过于频繁 | 按 Retry-After 重试 |
请求校验与平台异常
| code | HTTP | 形状 | 场景 | 处置 |
|---|---|---|---|---|
| 10001001 | 400 | 数组 | 请求字段校验失败，每字段一条；亦包括 emissaoDCe 段的注册 / 更新契约错误（两个配置块都缺、更新改 cnpj / 换市政、号段降号、换系列） | 按 mensagem 修正 |
| 10001000 | 500 | 裸对象 | 验证或身份核验调用的平台侧异常 | 退避重试；持续出现请携带失败请求的 timestamp 与路径联系平台 |
开票主体与证书
数组形状。见开票主体。
| codigo | HTTP | 场景 | 处置 |
|---|---|---|---|
GW001 | 400 | 注册：城市 / 州解析不到 IBGE 码；开票：收件人 IBGE 市政码不存在或与 uf 不一致 | 核对 UF 与城市名 / IBGE 码 |
CER0005 | 400 | 证书密码不符 | 核对密码 |
| 10003000 | 404 | empresaId 不存在或非本应用名下 | 核对 empresaId |
| 10003002 | 400 | CNPJ 已注册 | 该主体已存在，直接使用原 empresaId |
| 10003006 | 400 | 注册资料缺 IE | 补 inscricaoEstadual |
| 10003010 | 400 | 证书 CNPJ 与主体不一致 | 换正确证书 |
| 10003011 | 400 | 证书已过期 | 换有效证书 |
| 10003012 | 400 | 证书与现有证书重复 | 无需上传 |
| 10009033 | 400 | Webhook 注册参数不合法（id 不匹配 / contentType 非 JSON） | 按说明修正，见 Webhook 注册 |
NF-e
数组形状。业务错误为 HTTP 400；单据不存在为 HTTP 404，codigo 为 NFe0001。发行阶段的 SEFAZ 驳回不走 HTTP 错误，而是查询结果 Negada + webhook invoice.rejected。见 NF-e。
| codigo | HTTP | 场景 | 处置 |
|---|---|---|---|
NFe0001 | 404 | 查询 / 作废 / 更正函的 nfeId 不存在 | 核对开票时传入的 id 与 empresaId |
| 10004002 | 400 | 该 CNPJ 待处理开票任务超限 | 稍后重试 |
| 10004004 | 400 | 主体不可开票（未审批通过或证书未就绪） | 等待审批 / 关联证书 |
| 10004012 | 400 | 作废 / 更正函：票不在已授权状态 | 查询确认状态 |
| 10004013 | 400 | 作废：超出 24 小时窗口 | 改开退货票 |
| 10004014 | 400 | 作废：SEFAZ 拒绝（附返回码与原因） | 按 SEFAZ 原因处理 |
| 10004015 | 400 | 更正函：同票已达 20 封 | 不能再登记，需作废重开或退货票 |
| 10004016 | 400 | 更正函：SEFAZ 拒绝（附返回码与原因） | 按 SEFAZ 原因处理 |
| 10004017 | 400 | 更正函：内容净化后不足 15 字符 | 用葡语 / ASCII 文本重写 |
| 10004019 | 400 | 更正函：超出授权后 720 小时窗口 | 只能作废重开或退货票 |
| 10004021 至 10004026 | 400 | 退货票引用校验：缺引用 / 非退货票带引用 / 原票不存在或不属本主体 / 原票未授权 / 原票行不存在 / 数量超原票行 | 见 NF-e 开票的退货票规则 |
| 10004030 | 400 | ambienteEmissao 与主体当前环境不一致 | 按主体环境提交或联系运营切换，见环境 |
| 10004031 | 400 | 不支持的取值（presencaConsumidor / 多条支付 / 未知支付类型 / tipoPessoa 与证件不符 / CPF 买方携带 inscricaoEstadual） | 按 NF-e 开票的支持范围调整 |
| 10004034 | 400 | CNPJ 买方未传 cliente.inscricaoEstadual | 补买方 IE（ICMS 纳税人） |
| 10004043 | 400 | 契约字段缺失（税码所需的减基比例 / ST MVA 与税率 / 递延比例 / 按量单位税额 / IPI 税码 / pCredSN 请求与档案皆无），mensagem 点名字段路径 | 按 NF-e 开票的税码矩阵补字段 |
| 10004044 | 400 | 字段不适用于该税码（非 ST 税码带 substituicaoTributaria、非抵免税码带 percentualCreditoSimples） | 去掉该组 |
| 10004045 | 400 | CNPJ 买方的 cliente.inscricaoEstadual 不符合买方所在州的校验位规则（否则取号后被 SEFAZ 209 拒绝并烧号） | 核对买方 IE 与州 |
| 10004046 | 400 | 税码与主体税制不匹配（CRT 1/4 须三位 CSOSN，CRT 2/3 须两位 CST） | 按主体税制改税码 |
| 10004047 | 400 | 非纳税人买方使用了只对纳税人合法的税码（10/30/70、101/201/202/203）或携带 pCredSN | 改用 102 / 500 或不带抵免的 900 |
| 10005000 | 400 | 税务引擎校验拒绝（税制错配、ST 用于非纳税人、税率越界等） | 见 NF-e 开票的税参规则 |
CT-e
数组形状。业务错误为 HTTP 400；单据 / 任务不存在为 HTTP 404，codigo 为 CTe0001。发行阶段的 SEFAZ 驳回体现为查询结果 Negada + webhook cte.rejected。见 CT-e。
| codigo | HTTP | 场景 | 处置 |
|---|---|---|---|
CTe0001 | 404 | cteId 不存在或非本主体 | 核对 id 与 empresaId |
| 10003000 | 404 | empresaId 不存在 | 核对 empresaId |
| 10017004 | 400 | 主体不可发行（未审批 / 证书未就绪） | 等待审批 / 关联证书 |
| 10017005 / 10017006 | 400 | 同请求并发重复 / 该 CNPJ 待处理任务超限 | 稍后重试 |
| 10017007 | 400 | 号段无法确定（未配置或多个启用号段未指定） | 配置模型 57 号段 |
| 10017010 | 400 | ambienteEmissao 与主体环境不一致 | 按主体环境提交 |
| 10017011 | 400 | 市政 IBGE 码不存在 | 核对 codigoIbge |
| 10017012 / 10017013 | 400 | 参与方缺失 / 承担方与 IE 指示不符 | 补参与方或改 indicadorIeTomador |
| 10017014 | 400 | 单据引用不合法（缺失、chave 校验位错、三种类型混用、前序单据与服务类型不符） | 调整单据引用 |
| 10017015 | 400 | 单据类型与引用不符（补充 / 替代） | 按 tipo 补 ctesComplementados / cteSubstituido |
| 10017016 | 400 | 运费组成合计不等于总额，或 aReceber 大于总额 | 修正金额 |
| 10017017 / 10017018 / 10017019 | 400 | RNTRC 非法 / 模态不支持 / 枚举或格式非法（mensagem 点名字段） | 按 mensagem 修正 |
| 10017020 至 10017025 | 400 | 税参缺失 / 禁传 / 与税制不符 / 跨州非纳税人缺 icmsUfFim / 税率表缺项 / CST 不支持 | 见 CT-e 的税参说明 |
| 10017030 | 400 | 同 id 报文不同 | 换 id 或沿用原报文 |
| 10017031 | 400 | 生产环境同 id 已有在途 / 已授权单据 | 查询原单 |
| 10017040 至 10017045 | 400 | 状态不允许事件 / 超取消窗口 / 事件文本非法 / SEFAZ 拒绝事件 / 更正序号超限 / 被撤销事件不存在 | 见 CT-e 的取消与事件规则 |
| 10017048 / 10017049 | 400 | 已登记信函更正不可取消 / 信函更正超 720 小时窗口 | 见 CT-e 的取消与事件规则 |
| 10001001 | 400 | 请求字段校验失败（每字段一条） | 按 mensagem 修正 |
DC-e
数组形状。业务错误为 HTTP 400；单据 / 任务不存在为 HTTP 404，codigo 为 DCe0001。文档给出示例码的情形沿用该码值，其余 codigo 为平台错误码数字串。发行阶段的 SEFAZ 驳回体现为查询结果 Negada + webhook dce.rejected；取消阶段的 SEFAZ 拒绝走 dce.cancel_rejected。见 DC-e。
| codigo | HTTP | 场景 | 处置 |
|---|---|---|---|
DCe0001 | 404 | dceId 不存在、非本主体，或取消时单据尚未物化 | 核对 id 与 empresaId；Pendente 单据待授权后再取消 |
| 10003000 | 404 | empresaId 不存在 | 核对 empresaId |
DCe00004 | 400 | 主体未配置 DC-e 发行（缺 tipoEmitente / 模型 99 号段 / Marketplace 站点），或 ambiente 与主体当前环境不一致 | 注册时传 emissaoDCe 或带 id 更新补配；按主体当前环境提交，切生产联系运营 |
DCe00005 | 400 | Marketplace / Carrier 主体未传 remetente | 补发件方 |
DCe00006 | 400 | remetente.endereco 缺失 | 补发件方地址 |
DCe00007 | 400 | 巴西发件方缺 cpfCnpj | 补发件方证件 |
DCe00008 | 400 | 主体不可发行（未审批 / 证书未就绪） | 等待审批 / 关联证书 |
DCe00009 | 400 | 巴西收件方缺 cpfCnpj | 补收件方证件 |
GW001 | 400 | 市政 IBGE 码不存在或与 uf 不一致 | 核对 cidade / uf |
| 10019005 / 10019006 | 400 | 同请求并发重复 / 该 CNPJ 待处理任务超限 | 稍后重试 |
| 10019007 | 400 | 号段无法确定（多个启用号段） | 联系运营收敛号段 |
| 10019013 | 400 | 主体类型 Carrier 当前不支持发行 | 改用 Marketplace / OwnIssuer 主体 |
| 10019018 | 400 | 明细不合法（NCM 位数、数量 ≤ 0、单价为负） | 按 mensagem 修正 |
| 10019019 | 400 | 枚举或格式非法（mensagem 点名字段：tipoPessoa、modalidade、dataEmissao、证件、电话、邮箱、自发主体 remetente 与主体不符等） | 按 mensagem 修正 |
| 10019020 | 400 | 承运商 CNPJ 不合法 | 修正 cnpjTransportadora |
| 10019021 | 400 | 附加信息超长 | 缩短文本 |
| 10019022 | 400 | autorizacaoDownloadXml 条数或证件不合法；含发行方自身 CNPJ；同一证件重复 | 修正该列表 |
| 10019030 | 400 | 同 id 报文不同 | 换 id 或沿用原报文 |
| 10019031 | 400 | 生产环境同 id 已有在途 / 已授权单据 | 查询原单 |
| 10019040 至 10019043 | 400 | 状态不允许取消 / 超 24 小时窗口 / 取消已受理 / 理由不合法 | 见 DC-e 的取消规则 |
| 10019048 | 400 | dataEmissao 超出允许窗口（超前大于 5 分钟或回溯大于 30 天，mensagem 带当前允许范围） | 改用当前时刻或省略 dataEmissao |
| 10001001 | 400 | 请求字段校验失败（每字段一条）；emissaoDCe 的注册 / 更新契约错误 | 按 mensagem 修正 |
NF-e 验证
裸形状 {code, message}，HTTP 400，请求未进入校验流程。见 NF-e 验证。
| code | 接口 | 含义 | 处置 |
|---|---|---|---|
| 10015000 | XML 验证 | 请求体为空 | 在 body 中发送 XML |
| 10015001 | XML 验证 | 超过 1 MB | 真实单张 NF-e 不会超过此限制；检查是否包了一层或二次编码 |
| 10015002 | XML 验证 | 检测到 DTD（<!DOCTYPE） | 去除 DTD；作为 XXE 防护直接拒绝 |
| 10015003 | XML 验证 | 编码非 UTF-8 | 提交前转为 UTF-8 |
| 10015104 | chave 查询 | chave 非法（长度 / 字符 / 校验位） | 先本地校验：44 位数字；末位为 mod-11 校验位 |
| 10015004 | chave 查询 | 各数据源均查无此票 | 平台与官方数据源均无该 chave；与开票方核实 |
一级校验错误
以 HTTP 200 返回，位于 XML 验证响应的 validation.errors[]。这些不是传输错误：请求成功、单据不合格。除 PROTOCOL_MISSING（warning）外均为阻断项（终态 REJECTED）。
errors[].code | 数字码 | 含义 |
|---|---|---|
XML_MALFORMED | 10015100 | XML 语法非法 |
XSD_INVALID | 10015101 | 不符合 NF-e 4.00 XSD 版式 |
SIGNATURE_INVALID | 10015102 | 数字签名验证失败（内容被篡改，或签名时证书已过期） |
SIGNATURE_CERT_MISMATCH | 10015103 | 签名证书 CNPJ 与开票方不符 |
ACCESS_KEY_INVALID | 10015104 | chave 结构 / 校验位非法 |
ACCESS_KEY_MISMATCH | 10015105 | chave 分段与票面字段不一致 |
PROTOCOL_MISMATCH | 10015106 | 协议块与票内容不自洽 |
PROTOCOL_MISSING | 10015107 | 无协议节点（warning，不阻断） |
XML_VERSION_UNSUPPORTED | 10015108 | 版式版本非 4.00 |
二级结论
非 HTTP 错误：经 webhook invoice.verify.completed 送达。
validationStatus | 终态 | 处置 |
|---|---|---|
VALIDATED | 是 | 可放行（发货、结算） |
REJECTED | 是 | 不可放行；reason 说明 SEFAZ 判定（已取消 / 否决 / 作废 / 查无 / 协议不符） |
VALIDATION_ERROR | 否 | 平台侧核验失败，非发票判定；稍后带请求头 forceRevalidate: true 重新提交 |
身份核验
裸形状 {code, message}。格式与校验位错误由平台本地拦截，不会发往上游数据源，因此不消耗调用额度也不计费。见身份核验。
| code | HTTP | 责任方 | 含义 | 处置 |
|---|---|---|---|---|
| 10016000 | 400 | 调用方 | CPF 格式不合法（须 11 位数字） | 检查是否误传格式符或位数不足 |
| 10016001 | 400 | 调用方 | CPF 校验位不合法 | 本地先用 mod-11 算法校验 |
| 10016002 | 400 | 调用方 | 出生日期格式不合法（须 DDMMYYYY 有效日期） | 注意是日月年顺序，且须为真实存在的日期 |
| 10016003 | 400 | 调用方 | 未找到该 CPF 的信息 | 该 CPF 不存在，或 CPF 与出生日期不匹配（二者不作区分） |
| 10016004 | 451 | 第三方（上游依法拦截） | LGPD: menor de 16 anos (Lei Felca)，持有人小于 16 岁 | 依法不提供数据，勿重试 |
| 10016005 | 422 | 第三方（上游依法拦截） | LGPD: menor de idade，持有人 16 到 17 岁 | 依法不提供数据，勿重试 |
| 10016006 | 428 | 第三方（上游依法拦截） | LGPD: idade nao verificavel - informe a data de nascimento para completar a verificacao，年龄无法核实 | 平台已带出生日期补核验一次仍未通过，勿重试 |
| 10016010 | 400 | 调用方 | CNPJ 格式不合法（须 14 位数字） | 检查是否误传格式符 |
| 10016011 | 400 | 调用方 | CNPJ 校验位不合法 | 本地先用 mod-11 算法校验 |
| 10016012 | 400 | 调用方 | 未找到该 CNPJ 的信息 | 该 CNPJ 在官方登记中不存在 |
| 10016020 | 503 | 第三方（上游不可用） | 上游数据源暂不可用 | 指数退避重试（初始 1 秒，倍增至 30 秒上限，加抖动）；持续出现请联系平台 |
处理指引
- 401 / 403：配置错误；修正凭证、订阅或时钟。不要原样重试。
- 400 / 404：请求或业务规则问题；按码修正。少数码为暂时性，可稍后重试：10004002、10017005 / 10017006、10019005 / 10019006。
- 422 / 428 / 451：身份核验的法定拦截；重试无意义。
- 429：指数退避加抖动（初始 1 秒，倍增至 30 秒上限）。
- 503：按
Retry-After重试同一请求或链接（10009037、10016020）。 - 5xx：退避重试；持续失败请携带失败请求的
timestamp与路径联系平台。 - 信封
errorType：1API 错误、2SEFAZ 驳回、3系统异常（可重试）、4字段校验失败（修正请求）。 - 不要盲目重发被驳回的单据：
Negada与REJECTED是终态结论，先按 SEFAZ 原因处理。