TF Fiscal
开发文档

参考

错误码

TF Fiscal Open API 错误码合并参考,按层与领域分组,附 HTTP 状态、场景与处置建议。

错误格式

错误按产出层分三种格式,见通用约定:

层HTTP格式码字段
平台网关(鉴权、订阅、限流、请求体大小、文件下载链接)401 / 403 / 404 / 413 / 429 / 503平台统一响应体 {success, errorType, code, message}code(整数)
开票主体、NF-e、NFC-e、CT-e、DC-e、NFS-e、发票邮件、Webhook 注册400 / 404 / 409 / 500数组 [{codigo, mensagem}],每个问题一条codigo(字符串)
NF-e 验证与身份核验400 / 404 / 409 / 422 / 428 / 451 / 500 / 503无包装对象 {code, message}code(整数)
NFC-e 离线开票开放接口200 / 400 / 404平台统一响应体,业务错误也是 HTTP 200code(整数)
发票助手本机接口400 / 404 / 409 / 429 / 500 / 503;鉴权 401 / 403业务错误为数组 [{codigo, mensagem}];鉴权错误为平台统一响应体codigo / code
内置 SDK无异常对象的 Codigo 与 TipoCodigo(整数)

message 随 Language / Accept-Language 请求头本地化(默认葡语)。请按码分支,不要按文案分支。数组格式里的 codigo 一律是平台错误码的数字串。

各领域码段:

码段领域
10001xxx请求校验与平台异常
10003xxx开票主体与证书
10004xxxNF-e 开票、取消与更正函
10005xxx税务引擎
10009xxx开放平台(鉴权、订阅、限流、webhook、下载链接)
10013xxx文件下载
10015xxxNF-e 验证
10016xxx身份核验(CNPJ / CPF)
10017xxxCT-e
10018xxxNFS-e
10019xxxDC-e
10021xxx发票邮件
10022xxxNFC-e
10029xxxNFC-e 离线开票(开放接口、设备配对、离线开票内核、SDK、发票助手)

网关:鉴权与授权

平台统一响应体格式,在请求到达接口前产出。401 与 403 属配置错误,不修复就重试没有意义,还可能触发限流。签名方案见认证与签名。

HTTP错误码含义处置
40110009000缺少签名请求头(token / sign / timestamp)每次请求带全三个头
40110009001时间戳非法或时钟偏差超 ±300 秒校准时钟(NTP);每次请求重新生成时间戳,勿复用
40110009002token 无效核对 app_secret;如已轮换请更新配置
40110009003签名不匹配重新推导签名;见认证与签名的核对清单
40310009004应用已停用联系平台
40310009015应用未生效(待审批或已驳回)等待审批 / 联系平台
40310009014集成商账户已停用联系平台
40310009005接口未订阅为所调端点申请订阅
42910009006超出限流额度,或应用处于冷却期按 Retry-After 等待后重试,仍被拒再指数退避(初始 1 秒,倍增至 30 秒上限,加抖动);限流按应用与接口组两级实施,规则与响应头见限流与退避
41310009027请求体超过网关大小上限减小请求体;NF-e 验证每次只发送一张不超过 1 MB 的 NF-e

下载链接(linkDanfe、linkDownloadXml、linkDacce、nfeLinkXml、cteLinkDacte、dceLinkDace 等)是不带签名头的 GET 请求;失败以 HTTP 状态 + 平台统一响应体返回,见文件下载:

HTTP错误码含义处置
40110009035下载链接无效(路径被改、令牌挪用或签名不符)使用查询接口原样返回的链接
40110009036下载链接已过期重新调用查询接口获取新链接
50310009037文件尚未生成按 Retry-After 稍后重试同一链接
40410013011下载的文件不存在核对链接来源
42910013016回调链接的单 IP 下载过于频繁按 Retry-After 重试

请求校验与平台异常

错误码HTTP格式场景处置
10001001400数组请求字段校验失败,每字段一条;亦包括 emissaoDCe 段的注册 / 更新契约错误(两个配置块都缺、更新改 cnpj / 换市政、号段降号、换系列)按 mensagem 修正
10001000500数组或无包装对象平台侧异常;数组格式端点与验证、身份核验都可能返回退避重试;持续出现请携带失败请求的 timestamp 与路径联系平台

开票主体与证书

数组格式。见开票主体。

错误码HTTP场景处置
10003004400注册:城市 / 州解析不到 IBGE 码;开票:收件人 IBGE 市政码不存在或与 uf 不一致核对 UF 与城市名 / IBGE 码
10003008400证书密码不符核对密码
10003000404empresaId 不存在或非本应用名下核对 empresaId
10003002400CNPJ 已注册该主体已存在,直接使用原 empresaId
10003006400注册资料缺 IE补 inscricaoEstadual
10003010400证书 CNPJ 与主体不一致换正确证书
10003011400证书已过期换有效证书
10003012400证书与现有证书重复无需上传
10003050400自动注册:公开登记数据中查不到该 CNPJ核对 CNPJ
10003051503自动注册:公开登记数据暂不可用稍后原样重试
10003052400主体税制待确认(自动注册推不出税制),不能开新票带 id 调注册主体传 optanteSimplesNacional 与 mei
10003053400自动注册:登记地址的州或城市无法识别改用注册主体接口
10009033400Webhook 注册参数不合法(id 不匹配 / contentType 非 JSON / eventos 含未知编码)按说明修正,见 Webhook 注册
10009010400Webhook 回调地址不合法,只接受 http / https 地址改用公网 https 地址
10009013400Webhook 回调地址指向内网或保留网段改用公网地址
10009019400Webhook 回调地址过长缩短地址

税种

数组格式。税种不存在为 HTTP 404,并发修改为 HTTP 409,其余 HTTP 400。全部错误码见税种。

错误码HTTP场景处置
10005200404编号不存在或已删除核对编号与 empresaId
10005203400税码不受支持按 NF-e 开票的税码表修正
10005204400分类码不属于所填 CST分类码前三位须等于 CST
10005206409税种被并发修改重新查询后再提交
10005208400创建或整份替换的请求体带了 codigo删掉 codigo:编号由平台生成,创建响应返回,之后按路径传
10005210400请求体含不存在的字段,mensagem 点名路径删掉该字段,字段名以端点页为准
10005211400同一组两行的 cenario、tipoPessoa、naoContribuinte 组合重复合并或删掉其中一行
10005212400行的 cfop 首位与场景不符按场景改 CFOP:州内出库 5、跨州 6、出口 7,入库 1 / 2 / 3
10005213400数值或布尔传成了字符串,mensagem 点名路径数值传 JSON 数字,布尔传 true / false
10005214400CFOP 与组不符:ISSQN 行只能用 5933,ICMS 行不能用 5933按组改 CFOP
10005216400更新时 tipo 与现值不同税种类型不能改,另建一个税种
10005217400NFCe 税种带了 NFC-e 开票没有的字段,mensagem 点名路径删掉该字段,或改建 NFe 税种
10005218400该类型不能有的组:NFe 带 issqn,NFCe 带 ipi删掉该组
10005219400NFCe 税种的行场景不是 SaidaDentroEstado / Padrao改场景
10004047400非纳税人或个人买方的 ICMS 行用了纳税人专用税码(10、30、70、101、201、202、203)或带 percentualCreditoSimples改用 102 / 500 等税码,或去掉该维度
10005008400PIS / COFINS 01 行的 aliquota 与主体已配置计税制度的法定税率不符改成法定税率或不填,见开票主体的「税收制度」
10004046400税码与主体税制不符(CRT 1/4 须三位 CSOSN,CRT 2/3 须两位 CST)按主体税制改税码

NF-e

数组格式。业务错误为 HTTP 400;单据不存在为 HTTP 404,codigo 为 10004000 或 10004001。发行阶段的 SEFAZ 驳回不走 HTTP 错误,而是查询结果 Negada + webhook invoice.rejected。见 NF-e。

错误码HTTP场景处置
10004000 / 10004001404查询 / 取消 / 更正函的 nfeId 不存在核对开票时传入的 id 与 empresaId
10004002400该 CNPJ 待处理开票任务超限稍后重试
10004004400主体不可开票(未审批通过或证书未就绪)等待审批 / 关联证书
10004012400取消 / 更正函:票不在已授权状态查询确认状态
10004013400取消:超出 24 小时窗口改开退货票
10004014400取消:SEFAZ 拒绝(附返回码与原因)按 SEFAZ 原因处理
10004015400更正函:同票已达 20 封不能再登记,需取消重开或退货票
10004016400更正函:SEFAZ 拒绝(附返回码与原因)按 SEFAZ 原因处理
10004017400更正函:内容净化后不足 15 字符用葡语 / ASCII 文本重写
10004019400更正函:超出授权后 720 小时窗口只能取消重开或退货票
10004021 至 10004026400退货票引用校验:缺引用 / 非退货票带引用 / 原票不存在或不属本主体 / 原票未授权 / 原票行不存在 / 数量超原票行见 NF-e 开票的退货票规则
10004030400ambienteEmissao 与主体当前环境不一致按主体环境提交或联系运营切换,见环境
10004031400不支持的取值(presencaConsumidor / 多条支付 / 未知支付类型 / tipoPessoa 与证件不符 / CPF 买方携带 inscricaoEstadual)按 NF-e 开票的支持范围调整
10004034400CNPJ 买方未传 cliente.inscricaoEstadual补买方 IE(ICMS 纳税人)
10004043400契约字段缺失(税码所需的减基比例 / ST MVA 与税率 / 递延比例 / 按量单位税额 / IPI 税码 / pCredSN 请求与档案皆无),mensagem 点名字段路径按 NF-e 开票的税码矩阵补字段
10004044400字段不适用于该税码(非 ST 税码带 substituicaoTributaria、非抵免税码带 percentualCreditoSimples)去掉该组
10004045400CNPJ 买方的 cliente.inscricaoEstadual 不符合买方所在州的校验位规则(否则取号后被 SEFAZ 209 拒绝并烧号)核对买方 IE 与州
10004046400税码与主体税制不匹配(CRT 1/4 须三位 CSOSN,CRT 2/3 须两位 CST)按主体税制改税码
10004047400非纳税人买方使用了只对纳税人合法的税码(10/30/70、101/201/202/203)或携带 pCredSN改用 102 / 500 或不带抵免的 900
10004051400未传 IBGE 市政码,且无法按邮编补齐:邮编不在基础数据中、对应多个市政或属于别的州传 IBGE 码,或核对 cep / uf
10005000400税务引擎校验拒绝(税制错配、ST 用于非纳税人、税率越界等)见 NF-e 开票的税参规则
10005007400CRT 3 主体的 PIS / COFINS CST 01 没传税率,主体又未配置计税制度,平台无法补率传 aliquota,或在控制台「税务补录」里配置计税制度,见开票主体
10005008400CRT 3 主体的 PIS / COFINS CST 01 税率与主体计税制度的法定税率不符改成法定税率或不传,见开票主体
10005202400商品行引用的税种不存在、已删除或属于别的主体核对 classeImposto 与 empresaId,见税种
10005215400引用的税种类型与单据不符:NF-e 只能引用 NFe 税种,NFC-e 只能引用 NFCe 税种改引用对应类型的税种
10005220400引用的税种与主体当前税制不符(IncompativelComRegime)按新税制整份替换税种,见税种
10001002400引用税种的商品行直传了 icms 或 issqn 却没传 cfop在该商品行补 cfop
10005209400引用的税种在本行需要的组(ICMS 或服务行 ISSQN、PIS、COFINS)里没有适用于本票的行,mensagem 写明组、场景、客户类型与是否非纳税人给税种补一行,或在请求里直传该组,见税种的选行顺序

NFC-e

数组格式。业务错误为 HTTP 400;单据或主体不存在为 HTTP 404。SEFAZ 驳回不走 HTTP 错误,而是查询结果 Negada + webhook nfce.rejected。见 NFC-e。

错误码HTTP场景处置
10022006404nfceId 不存在核对 id 与 empresaId
10003000404empresaId 不存在核对 empresaId
10022001400主体当前环境未开通 NFC-e注册或更新时传 emissaoNFeConsumidor 的对应环境
10022002400主体不可开票(未审批通过或证书不可用)等待审批或关联证书
10022003400ambienteEmissao 与主体当前环境不一致按主体环境提交
10022004400不符合 NFC-e 规则,mensagem 点名原因按原因修正,或改开 NF-e
10022007400超出取消期限(取消 30 分钟、替代取消 168 小时)按州规定另开 NF-e 冲销
10022008400当前状态不允许此操作(不是已授权、取消处理中)查询确认状态
10022009400州要求二维码 v2,但主体没有可用的安全码二维码 v2 由平台为主体切换,安全码只在生产环境生效,请联系平台
10022024400未传 IBGE 市政码,且无法按邮编补齐:邮编不在基础数据中、对应多个市政或属于别的州传 IBGE 码,或核对 cep / uf
10001001400请求字段校验失败按 mensagem 修正
10005000400税务引擎校验拒绝按 mensagem 修正
10005007400CRT 3 主体的 PIS / COFINS CST 01 没传税率,主体又未配置计税制度,平台无法补率传 aliquota,或在控制台「税务补录」里配置计税制度,见开票主体
10005008400CRT 3 主体的 PIS / COFINS CST 01 税率与主体计税制度的法定税率不符改成法定税率或不传,见开票主体
10005202400商品行引用的税种不存在、已删除或属于别的主体核对 classeImposto 与 empresaId,见税种
10005215400引用的税种类型与单据不符:NF-e 只能引用 NFe 税种,NFC-e 只能引用 NFCe 税种改引用对应类型的税种
10005220400引用的税种与主体当前税制不符(IncompativelComRegime)按新税制整份替换税种,见税种
10001002400引用税种的商品行直传了 icms 或 issqn 却没传 cfop在该商品行补 cfop
10005209400引用的税种在本行需要的组(ICMS 或服务行 ISSQN、PIS、COFINS)里没有适用于本票的行,mensagem 写明组、场景、客户类型与是否非纳税人给税种补一行,或在请求里直传该组,见税种的选行顺序
10005205400税种选中的行含 NFC-e 不接受的组或字段,mensagem 点名字段为 NFC-e 另建一个税种,或在请求里传该组覆盖

10022004 常见原因:在场方式不允许;送货、取货地址跨州或买方是纳税人;金额超上限;未达识别要求;配送缺承运方或地址,或非配送填了承运方、运费方式;本州不允许配送;CFOP 或税码不在 NFC-e 允许范围;支付不足、找零不符或用了 SemPagamento,或刷卡组、支付说明用在不允许的支付方式上;携带 NFC-e 不允许的字段(一次列出全部);取值名未知。

SEFAZ 常见驳回(motivoStatus 原样回显):704 开票时刻早于 SEFAZ 收到时刻 5 分钟以上;717 在场方式不允许;725 CFOP 不允许;750 达到识别门槛但未识别消费者;780 超过州金额上限;785 / 786 / 787 / 788 本州不允许配送、配送缺承运方、缺消费者、缺地址;462 / 463 / 464 安全码未登记、已停用、二维码校验不符;865 支付合计小于票面总额。

NFC-e 离线开票

见 NFC-e 离线开票。

开放接口

平台统一响应体。业务错误为 HTTP 200、success 为 false;主体、设备不存在为 HTTP 404;字段校验失败为 HTTP 400。

错误码HTTP场景处置
10029100404主体不存在或不属于当前集成商核对 empresaId
10029202404设备不存在或不属于该主体核对 dispositivoId
10029101200主体不能开 NFC-e:尚未通过运营审核、审核被驳回或已停用,所选环境未开通 NFC-e,或生产环境缺少有效 A1 证书;message 说明原因新注册的主体需等待运营审核通过后再开通离线开票、生成配对码;驳回的按原因修改后重新提交;注册时传 emissaoNFeConsumidor;关联有效证书
10029104200该主体的离线开票被平台停用联系平台
10029201200主体待使用的配对码已有 20 个先使用或等待过期
10029219200ambiente 与主体当前环境不一致按主体当前环境生成配对码
10029221200serie 在 890 到 999 之间;CNPJ 开票方的 NFC-e 只能用 0 到 889 号系列换 0 到 889 内的系列
10029222200serie 是主体档案里任一环境的 NFC-e 系列换一个系列
10029223200serie 已被本主体其他在用设备或待使用的配对码占用;message 说明占用者换一个系列
10029224200numeroInicial 不大于该系列平台已知的最大号;message 给出这个号码传更大的起始号码,或不传由平台接着往后
10029225200serie 属于已停用或被吊销、但还有离线票没补传完的设备等原设备补传完成后再生成
10029001200参数取值超出范围,message 点名字段按允许取值修正
10001001400请求字段校验失败按 message 修正

设备配对

发票助手或 SDK 配对时由平台返回,发票助手的安装向导与 SDK 异常原样展示。

错误码场景处置
10029203 / 10029204设备已停用 / 已被平台吊销重新生成配对码
10029205配对码无效核对是否完整复制;必要时重新生成
10029206 / 10029207 / 10029208配对码已过期 / 已使用 / 已作废重新生成配对码
10029209配对码不允许该形态(例如 Assistente 码用于 SDK)按接入形态重新生成
10029210SDK 配对未提供收银软件名称初始化时传收银软件名称
10029501收银软件被平台封禁联系平台
10029211收银程序版本被封禁或低于最低版本升级收银程序
10029212内核版本过旧升级发票助手或 SDK
10029213证书 CNPJ 与主体不符选用该主体的 A1 证书
10029214证书已过期更换有效证书
10029219配对码环境与主体当前环境不一致(配对时再核对一次)在主体当前环境重新生成配对码
10029221 到 10029225配对码指定的设备系列在配对时再核对一次,已不可用;含义同生成配对码时的同号错误重新生成配对码,换一个系列或起始号码
10029307设备环境与主体当前环境不一致:主体切换环境后,旧环境设备在线开票与补传都被拒绝在主体当前环境重新生成配对码、配对新设备,停用旧设备
10029424设备在线开票的号码已被占用;内核弃号重试一次仍冲突时返回本机库与平台记录不一致,导出日志联系平台
10029426设备在线开票时,同一 id 在平台已有未被拒绝的票核对原票;新的销售用新 id

离线开票内核与 SDK

发票助手与内置 SDK 共用离线开票内核。内核错误在 SDK 中以异常抛出(Codigo 为错误码、Tipo 为常量),在发票助手本机接口中以 codigo 返回。10029800 段与 10029780 段来自内核,10029870 段来自 SDK 与运行时通信;只因 SDK 自身缺陷才会出现的码不在此列,见 SDK 参考。平台返回的错误码原样透传。

错误码常量场景处理
10029780ENGINE_TAX_CLASS_REQUIRES_ONLINE商品行引用了税种,但连不上平台展开;未占用票号,发票助手返回 HTTP 400恢复网络后用同一 id 重发;断网时商品行改传 impostos,见税种与联网
10029801ENGINE_NOT_ACTIVATED该主体未在本机配对,或本机尚未配对任何主体引导配对;多主体时检查 empresaId
10029802ENGINE_EMPRESA_REQUIRED配对了多个主体但未指定 empresaId传 empresaId
10029803ENGINE_LICENSE_MISSING没有可用于离线开票的许可证联网同步一次(SincronizarAgora)
10029804ENGINE_LICENSE_EXPIRED许可证已过期;离线开票被拒,在线开票照常恢复网络,自动续签
10029805ENGINE_LICENSE_SIGNATURE_INVALID许可证签名无效人工处理:联系平台,本地库可能被篡改
10029806ENGINE_LICENSE_NOT_FOR_DEVICE许可证不属于本设备人工处理:重新配对
10029807ENGINE_OFFLINE_WINDOW_CLOSED已过离线开票截止时间恢复网络后在线开票
10029808ENGINE_LICENSE_QUOTA_EXHAUSTED本设备系列号码已用到 999999999停用该设备,生成指定新系列(serie)的配对码重新配对;平台不会自动更换系列
10029809ENGINE_CLOCK_ROLLBACK系统时钟被往回调人工处理:校正系统时间
10029810ENGINE_TRANSMISSION_DEADLINE_REACHED最早待补传票已超补传时限人工处理:尽快恢复网络补传
10029811ENGINE_OFFLINE_NOT_ALLOWED主体或州不允许离线开票;或刚从备份恢复、尚未拿到新许可证只能在线开票;刚恢复的联网同步一轮后自动恢复离线开票
10029812ENGINE_OFFLINE_FUEL_NOT_SUPPORTED含燃料的票不能离线开网络恢复后开票
10029813ENGINE_CERTIFICATE_UNAVAILABLE证书找不到、无私钥或 CNPJ 不符人工处理:检查证书存储,必要时 TrocarCertificado
10029814ENGINE_CERTIFICATE_EXPIRED证书已过期人工处理:续期后 TrocarCertificado
10029815ENGINE_SNAPSHOT_MISSING本机配置或计税数据缺失或校验失败联网同步;持续出现联系平台
10029816ENGINE_DEVICE_DEACTIVATED设备已被停用人工处理:联系集成商;已开离线票照常补传
10029817ENGINE_REQUEST_INVALID请求校验失败,Detalhes 逐字段列出原因修正请求;可先用 Previsualizar 预校验
10029818ENGINE_DUPLICATE_ID_DIFFERENT_CONTENT同一 id 已用于内容不同的票新单用新 id;重试用原请求取回原票
10029819ENGINE_NOTE_NOT_FOUND本机没有这张票核对 id 与 empresaId
10029820ENGINE_NOTE_NOT_CORRECTABLE当前状态不可修正只有 Rejeitada 可以 Substituir
10029821ENGINE_CORRECTION_CHANGES_TOTALS修正改变了金额或税额只改非金额内容
10029822ENGINE_CANCEL_NOT_ALLOWED当前状态不可取消;替代取消时原票不是在线开出的正常票(离线票、已取消或已有挂起取消)不要重试
10029823ENGINE_SERIE_EXHAUSTED设备系列号码已用尽停用该设备,生成指定新系列(serie)的配对码重新配对;平台不会自动更换系列
10029824ENGINE_PLATFORM_UNREACHABLE需要联网的操作(配对)连不上平台检查网络后重试
10029825ENGINE_ACTIVATION_CODE_INVALID配对码格式、签名或有效期不对人工处理:重新生成配对码
10029826ENGINE_ACTIVATION_HOST_UNTRUSTED配对码指向的平台地址不受信人工处理:确认配对码来源与安装包环境(测试 / 生产)
10029827ENGINE_KEY_PROTECTION_FAILED数据目录来自别的电脑或别的 Windows 用户人工处理:用原电脑、原用户运行,或重新配对
10029828ENGINE_DATA_DIR_LOCKED数据目录被其他进程占用,包括恢复备份时本程序还没 Encerrar 的实例关闭另一个实例;恢复备份前先 Encerrar
10029829ENGINE_LOCAL_STORE_CORRUPTED本地库不一致人工处理:不要删除数据目录,联系平台
10029830ENGINE_PROTOCOL_VERSION_UNSUPPORTEDSDK 与运行时版本不兼容SDK 与运行时配套升级
10029831ENGINE_RUNTIME_START_FAILED运行时启动失败检查运行时目录是否完整、是否被杀毒软件拦截
10029832ENGINE_RUNTIME_CRASHED运行时意外退出可重试;开启自动重启时 SDK 自行恢复,开票用同一 id 重发
10029833ENGINE_TIMEOUT等待超时开票用同一 id 重发,或先 Consultar
10029834ENGINE_SHUTTING_DOWN正在关闭或已关闭重新 Iniciar
10029835ENGINE_IN_PROCESS_UNSUPPORTEDJava 进程内模式需要 Java 21 及以上改用子进程模式
10029836ENGINE_INTERNAL_ERROR内核内部错误,说明里带定位号联系平台并提供定位号与日志
10029837ENGINE_ALREADY_ACTIVATED该主体已在本数据目录配对无需再配对;换设备须先停用旧设备
10029838ENGINE_PLATFORM_RESPONSE_UNTRUSTED平台响应校验失败,已保留原数据稍后自动重试;持续出现检查网络代理是否改写了响应
10029839ENGINE_ACTIVATION_PERSIST_FAILED平台已配对但本机保存失败用同一配对码再次配对
10029840ENGINE_CONFIG_INVALID初始化配置非法修正配置
10029841ENGINE_AUTHORIZED_XML_UNAVAILABLE授权 XML 不可用:尚未授权,或本机没有且向平台回取不到等授权事件后再取;回取不到时稍后重试
10029842ENGINE_LOCAL_STORE_NEWER_VERSION数据目录被更新版本用过,内核拒绝启动;发票助手本机接口返回 HTTP 503安装或升级到不低于上次使用的版本;不要删除数据目录
10029843ENGINE_CANCEL_XML_UNAVAILABLE取消 XML 不可用:尚未取消,或本机没有且向平台回取不到等取消成功事件后再取;回取不到时稍后重试
10029844ENGINE_EXPORT_FAILED导出或备份写文件失败:目标不可写,或备份文件已存在换目录或文件名;检查磁盘空间与权限
10029845ENGINE_SUBSTITUTE_KEY_INVALID替代取消的替代票密钥不合法,或不是本设备本主体未被拒收的离线票传本设备为同一笔销售开出的离线票 44 位密钥
10029846ENGINE_BACKUP_INVALID备份无法恢复:口令错误,或备份文件被改动、损坏、不是离线开票的备份;发票助手返回 HTTP 400核对备份口令;换一份完好的备份。原库保持不变
10029874ENGINE_PARAMS_INVALID参数缺失或类型错误,Detalhes.campo 点名参数修正参数,例如请求不是 JSON 对象、证书指纹格式、日期格式
10029877ENGINE_RUNTIME_NOT_FOUND找不到运行时检查安装包与运行时目录
10029878ENGINE_TOO_MANY_PENDING同时等待中的调用超过 64 个降低并发
10029880ENGINE_PRINCIPAL_UNREACHABLE主从模式的从机连不上主机,请求没有送到稍后重试,或把收银切到备用机
10029881ENGINE_PRINCIPAL_RESULT_UNKNOWN请求已发到主机但没收到响应,结果未知主机恢复后用同一个 id 查询;同一 id 同样内容重开不会重复开票
10029882ENGINE_TERMINAL_TOKEN_INVALID从机的终端令牌无效或已吊销在主机重新签发终端令牌,更新从机配置
10029883ENGINE_PRINCIPAL_ADDRESS_INVALID主机地址格式不对,或不是局域网私有地址修正从机配置的主机地址
10029884ENGINE_MODE_METHOD_UNAVAILABLE当前模式不提供该方法配对、换证书、备份与导出在主机做;终端管理只在主机调用
10029885ENGINE_PRINCIPAL_REJECTED主机拒绝了请求来源,例如从机不在允许网段内检查主机的允许网段与网络
10029886ENGINE_PRINCIPAL_RATE_LIMITED鉴权失败过多,被主机限频核对令牌,1 分钟后再试
10029887ENGINE_PRINCIPAL_LISTEN_FAILED主机的局域网端口无法监听换主机端口,或释放被占用的端口
10029888ENGINE_TERMINAL_NOT_FOUND要吊销的终端不存在核对终端标识

发票助手

错误码HTTP场景处置
10029900401缺少收银令牌带 Authorization: Bearer tfl_…
10029901401收银令牌无效或已吊销店长重新生成令牌
10029902403令牌无权访问该主体生成包含该主体的令牌
10029903403来源地址不在局域网允许网段检查局域网模式设置
10029904400回调地址不合法只允许 http / https;局域网模式关闭时只允许本机回环地址
10029905401桌面程序操作需要店长会话输入店长 PIN 登录
10029906401店长 PIN 错误重新输入;累计输错 5 次会锁定
10029907409打印机不可用检查打印机连接与「设置」里选的打印机
10029908409尚未完成安装向导先完成安装向导
10029909400请求不合法按 mensagem 修正
10029910404资源不存在核对路径
10029911400PIN 格式不对,须为 6 到 8 位数字按格式重新设置
10029912500助手内部错误导出诊断包联系平台
10029913403桌面程序请求的 Host 头不被允许,只接受 127.0.0.1、localhost 或 [::1] 加助手端口用 http://127.0.0.1:端口 打开桌面程序,不要经代理或其他主机名访问
10029914429PIN 错误次数过多,锁定中等锁定结束,见发票助手常见问题
10029916409所选端口被占用或无法监听,设置未修改换一个端口
10029917403收银员会话无权访问该主体由店长 PIN 登录后操作
10029918429助手忙:XML 回取已有 3 个在进行,或已有一项导出、备份在进行稍后重试,不要连续重复调用
10029919400出站代理设置不合法在桌面程序「设置」按提示修正出站代理的「联网方式」与「代理地址」,设置未保存
10029920409保存出站代理或从备份恢复时要重启开票内核,但有导出、备份或 XML 下载在进行,15 秒内没有结束等这些操作结束后再保存或再恢复;设置与本地库都没有改动
10029922409助手数据目录所在磁盘剩余空间不足 256 MB,导出、备份或上传备份文件被拒清理该磁盘后重试
10029923403桌面程序的请求缺少或带错防跨站令牌,常见于会话过期或页面停留过久刷新页面;仍出现时重新输入店长 PIN 登录
10029924429收银员会话开设过于频繁,同一来源每分钟最多 20 次等一分钟后再进入开票页

发票助手错误只出现在助手的本机接口与桌面程序中,内置 SDK 不会返回;10029905 到 10029908、10029911、10029913 到 10029917、10029919 到 10029924 只在桌面程序中出现。

CT-e

数组格式。业务错误为 HTTP 400;单据 / 任务不存在为 HTTP 404,codigo 为 10017002 或 10017003。发行阶段的 SEFAZ 驳回体现为查询结果 Negada + webhook cte.rejected。见 CT-e。

错误码HTTP场景处置
10017002 / 10017003404cteId 不存在或非本主体核对 id 与 empresaId
10003000404empresaId 不存在核对 empresaId
10017004400主体不可发行(未审批 / 证书未就绪)等待审批 / 关联证书
10017005 / 10017006400同请求并发重复 / 该 CNPJ 待处理任务超限稍后重试
10017007400号段无法确定(未配置或多个启用号段未指定)配置模型 57 号段
10017010400ambienteEmissao 与主体环境不一致按主体环境提交
10017011400市政 IBGE 码不存在核对 codigoIbge
10017050400未传 codigoIbge,且无法按邮编补齐:缺 cep、邮编不在基础数据中或对应多个市政传 codigoIbge,或核对 cep
10017012 / 10017013400参与方缺失 / 承担方与 IE 指示不符补参与方或改 indicadorIeTomador
10017014400单据引用不合法(缺失、chave 校验位错、三种类型混用、前序单据与服务类型不符)调整单据引用
10017015400单据类型与引用不符(补充 / 替代)按 tipo 补 ctesComplementados / cteSubstituido
10017016400运费组成合计不等于总额,或 aReceber 大于总额修正金额
10017017 / 10017018 / 10017019400RNTRC 非法 / 模态不支持 / 枚举或格式非法(mensagem 点名字段)按 mensagem 修正
10017020 至 10017025400税参缺失 / 禁传 / 与税制不符 / 跨州非纳税人缺 icmsUfFim / 税率表缺项 / CST 不支持见 CT-e 的税参说明
10017030400同 id 报文不同换 id 或沿用原报文
10017031400生产环境同 id 已有在途 / 已授权单据查询原单
10017040 至 10017045400状态不允许事件 / 超取消窗口 / 事件文本非法 / SEFAZ 拒绝事件 / 更正序号超限 / 被撤销事件不存在见 CT-e 的取消与事件规则
10017048 / 10017049400已登记信函更正不可取消 / 信函更正超 720 小时窗口见 CT-e 的取消与事件规则
10001001400请求字段校验失败(每字段一条)按 mensagem 修正

DC-e

数组格式。业务错误为 HTTP 400;单据 / 任务不存在为 HTTP 404,codigo 为 10019002 或 10019003。发行阶段的 SEFAZ 驳回体现为查询结果 Negada + webhook dce.rejected;取消阶段的 SEFAZ 拒绝走 dce.cancel_rejected。见 DC-e。

错误码HTTP场景处置
10019002 / 10019003404dceId 不存在、非本主体,或取消时单据尚未物化核对 id 与 empresaId;Pendente 单据待授权后再取消
10003000404empresaId 不存在核对 empresaId
10019012 / 10019010400主体未配置 DC-e 发行(缺 tipoEmitente / 模型 99 号段 / Marketplace 站点),或 ambiente 与主体当前环境不一致注册时传 emissaoDCe 或带 id 更新补配;按主体当前环境提交,切生产联系运营
10019014400Marketplace / Carrier 主体未传 remetente补发件方
10019015400remetente.endereco 缺失补发件方地址
10019016400巴西发件方缺 cpfCnpj补发件方证件
10019004400主体不可发行(未审批 / 证书未就绪)等待审批 / 关联证书
10019017400巴西收件方缺 cpfCnpj补收件方证件
10019011400市政 IBGE 码不存在或与 uf 不一致核对 cidade / uf
10019049400未传 IBGE 市政码,且无法按邮编补齐:邮编不在基础数据中、对应多个市政或属于别的州传 IBGE 码,或核对 cep / uf
10019005 / 10019006400同请求并发重复 / 该 CNPJ 待处理任务超限稍后重试
10019007400号段无法确定(多个启用号段)联系运营收敛号段
10019013400主体类型 Carrier 当前不支持发行改用 Marketplace / OwnIssuer 主体
10019018400明细不合法(NCM 位数、数量 ≤ 0、单价为负)按 mensagem 修正
10019019400枚举或格式非法(mensagem 点名字段:tipoPessoa、modalidade、dataEmissao、证件、电话、邮箱、自发主体 remetente 与主体不符等)按 mensagem 修正
10019020400承运商 CNPJ 不合法修正 cnpjTransportadora
10019021400附加信息超长缩短文本
10019022400autorizacaoDownloadXml 条数或证件不合法;含发行方自身 CNPJ;同一证件重复修正该列表
10019030400同 id 报文不同换 id 或沿用原报文
10019031400生产环境同 id 已有在途 / 已授权单据查询原单
10019040 至 10019043400状态不允许取消 / 超 24 小时窗口 / 取消已受理 / 理由不合法见 DC-e 的取消规则
10019048400dataEmissao 超出允许窗口(超前大于 5 分钟或回溯大于 30 天,mensagem 带当前允许范围)改用当前时刻或省略 dataEmissao
10001001400请求字段校验失败(每字段一条);emissaoDCe 的注册 / 更新契约错误按 mensagem 修正

NFS-e

数组格式 [{codigo, mensagem}];业务错误为 HTTP 400;单据不存在为 HTTP 404,codigo 为 10018002 或 10018003。发行是异步的:受理期的拒绝是同步 HTTP 错误,发行方的驳回体现为查询结果 Negada + webhook nfse.rejected。见 NFS-e。

错误码HTTP场景处置
10018001400受理期参数校验拒绝,mensagem 说明具体原因(含 IBS/CBS 门控未生效、圣保罗主体携带 ibsCbs、码值或结构约束不满足)按 mensagem 修正
10018002 / 10018003404单据不存在:nfseId 不属于本主体,或进项密钥不在本主体的进项里核对 nfseId / chaveAcesso 与 empresaId
10018004400主体不可开票(停用 / 证书不可用)检查主体状态与证书
10018005400主体缺 NFS-e 档案,mensagem 点名缺哪一项注册时传 emissaoNFSe 或带 id 更新补配
10018010400该市镇的 NFS-e 标准尚未支持该市镇暂不可开,联系平台
10018012400服务码不在 LC 116 官方清单内核对 codigoTributacaoNacional
10018013400接收方证件不合法核对 CPF / CNPJ / NIF
10018014400服务出口缺出境国补 servico.paisPrestacao
10018015400被替代票不可替代核对被替代票状态
10018020400无法确定 ISS 税率(直传与市政参数均无)传 servico.iss.aliquota 或正确的 servico.codigoTributacaoMunicipal
10018022400Simples 主体不得直传 ISS 税率去掉 aliquota
10018023400判定联邦源泉扣缴还缺以下信息,请补充或直接传扣缴额:%s。%s 一次列出全部缺的字段路径:servico.retencoes.categoriaFederal、cliente.orgaoPublico、cliente.optanteSimplesNacional、servico.retencoes.modoContratacao、servico.retencoes.anexoSimples、servico.retencoes.inss/irrf/csll/pis/cofins补齐所列字段后重发,或在 servico.retencoes 直传扣缴额,无扣缴传 0;清单含 servico.retencoes.inss/irrf/csll/pis/cofins 时只能直传,见于服务分类要求人工判定、或本主体以接收方或中介方身份开票
10018030 / 10018031400同一请求正在处理中 / 该单号已开票或同 id 不同内容稍后重试;换单号或核对内容
10018040400取消分析申请已在处理中等市镇裁决
10018041400该票已被替代不可再操作
10018042400当前状态不允许该事件(取消;进项票表态:已取消 / 已被替代 / 已有表态 / 本主体非接收方或中介方)核对票状态,一张票每方只能表态一次
10018063400DPS 报文不符合官方 XSD,明细含行号、列号、错误键与元素名常见原因是文本含 Latin-1 以外字符、地址不完整、码值不在官方码表
10018064400NFS-e 事件报文不符合官方 XSD核对 motivo 长度(15-255)、codigoMotivo 取值与字符集
10018065400本票需要的 NFS-e 计税基础数据未导入,请在请求中直接传入箭头后的字段,或先导入基础数据:%s。%s 按「业务项 -> 可改传的请求字段」列出:retencao-federal -> servico.retencoes.inss/irrf/csll/pis/cofins、pis-cofins -> servico.pisCofins.aliquotaPis/aliquotaCofins、iss-local-incidencia -> servico.iss.municipioIncidencia.codigoIbge;只在请求没给、须由平台查的那一项用到未就绪的数据时出现,一律在受理时返回在请求里直接传箭头后的字段,或联系平台确认基础数据已导入;iss-local-incidencia 出现于服务发生地与开票方不同城时,传 servico.iss.municipioIncidencia 即可
10018066400未传 IBGE 市政码,且无法按邮编补齐:邮编不在基础数据中、对应多个市政或属于别的州传 IBGE 码,或核对 cep / uf

发票邮件

数组格式。业务错误为 HTTP 400;查无为 HTTP 404;同一张票上一封邮件未到终态为 HTTP 409。投递失败不走 HTTP 错误,而是查询结果 Falha + webhook email.failed。见发票邮件。

错误码HTTP场景处置
10003000404empresaId 不存在核对 empresaId
10021001404邮件模板不存在或不属于本集成商核对 templateId
10021002400模板已停用,或模板的发票类型与单据不符换模板或启用
10021003400模板引用了白名单之外的变量按变量枚举修正
10021004400模板 HTML 含禁止的内容或正文超过 64 KB按消息点名的位置修正
10021005400模板列表的 tipoDocumento 不支持只传 NFe / NFSe / CTe / DCe
10021010404发票不存在或不属于本主体核对 documentoId、tipoDocumento 与 empresaId
10021011400发票尚未授权,或已取消、已被替代授权后再发
10021012400该发票类型没有默认模板传 templateId 或设默认模板
10021013400没有收件人传 destinatarios
10021015409同一张票上一封邮件尚未到终态等 Enviado 或 Falha 后用新 id 重发
10021020404邮件不存在或不属于本主体核对 emailId 与 empresaId
10001001400请求字段校验失败(每字段一条)按 mensagem 修正

NF-e 验证

无包装的 {code, message} 对象,见 NF-e 验证。XML 验证与 chave 查询的请求级错误为 HTTP 400,请求未进入校验流程:

错误码接口含义处置
10015000XML 验证请求体为空在 body 中发送 XML
10015001XML 验证超过 1 MB真实单张 NF-e 不会超过此限制;检查是否包了一层或二次编码
10015002XML 验证检测到 DTD(<!DOCTYPE)去除 DTD
10015003XML 验证编码非 UTF-8提交前转为 UTF-8
10015005XML 验证已停用,不再返回(原含义:该 chave 已由其他集成商提交验证)无需处理:不同集成商可各自验证同一张票
10015104chave 查询chave 非法(长度 / 字符 / 校验位)先本地校验:44 位数字;末位为 mod-11 校验位
10015004chave 查询各数据源均查无此票平台与官方数据源均无该 chave;与开票方核实

DANFE 获取

DANFE 获取失败时按下表返回 HTTP 状态与无包装的 {code, message} 对象;即使请求头带 Accept: application/pdf,错误也以 JSON 返回。

错误码HTTP含义处置
10015104400chave 非法(长度 / 字符 / 校验位)先本地校验:44 位数字;末位为 mod-11 校验位
10015300404本账户没有这张票的验证记录(其他集成商验证过也一样)先用 XML 验证 提交这张票;不要重试
10015301409验证还没完成(PENDING_SEFAZ / VALIDATING)收到 invoice.verify.completed 后再取
10015302409当前结论不出 PDF(只有 VALIDATED 与 status 为 Cancelada 的票出 PDF)不要重试
10015303409平台缺这张票的 XML 原文用 XML 验证原样重新提交这份 XML、不带 forceRevalidate,再取
10015304503XML 原文还在归档按 Retry-After(5 秒)后重试
10015305503生成繁忙或暂时不可用按 Retry-After 后重试
10001000500平台内部错误退避重试;持续失败请携带请求的 timestamp 与路径联系平台

一级校验错误

以 HTTP 200 返回,位于 XML 验证响应的 validation.errors[]。这些不是传输错误:请求成功、单据不合格。除 PROTOCOL_MISSING(warning)外均为阻断项(终态 REJECTED)。

errors[].code数字码含义
XML_MALFORMED10015100XML 语法非法
XSD_INVALID10015101不符合 NF-e 4.00 XSD 版式
SIGNATURE_INVALID10015102数字签名验证失败(内容被篡改,或签名时证书已过期)
SIGNATURE_CERT_MISMATCH10015103签名证书 CNPJ 与开票方不符
ACCESS_KEY_INVALID10015104chave 结构 / 校验位非法
ACCESS_KEY_MISMATCH10015105chave 分段与票面字段不一致
PROTOCOL_MISMATCH10015106协议块与票内容不自洽
PROTOCOL_MISSING10015107无协议节点(warning,不阻断)
XML_VERSION_UNSUPPORTED10015108版式版本非 4.00

二级结论

非 HTTP 错误:经 webhook invoice.verify.completed 送达。

validationStatus终态处置
VALIDATED是可放行(发货、结算)
REJECTED是不可放行;reason 说明 SEFAZ 判定(已取消 / 否决 / 作废 / 查无 / 协议不符)
VALIDATION_ERROR(status 为 null)是,可重试平台侧核验失败,非发票判定;与其他结论一样 24 小时内复用,请稍后带请求头 forceRevalidate: true 重新提交
VALIDATION_ERROR(status 为 Desconhecida)是,重试不会改变SEFAZ 不受理这张票的查询(如 cStat 526,开具时间过久),非发票判定,不代表发票是假的;结论一直复用,无需重试,需要时用其他方式确认

身份核验

无包装的 {code, message} 对象。格式与校验位错误由平台本地拦截,不会发往上游数据源,因此不消耗调用额度也不计费。见身份核验。

错误码HTTP责任方含义处置
10016000400调用方CPF 格式不合法(须 11 位数字)检查是否误传格式符或位数不足
10016001400调用方CPF 校验位不合法本地先用 mod-11 算法校验
10016002400调用方出生日期格式不合法(须 DDMMYYYY 有效日期)注意是日月年顺序,且须为真实存在的日期
10016003400调用方未找到该 CPF 的信息该 CPF 不存在,或 CPF 与出生日期不匹配(二者不作区分)
10016004451第三方(上游依法拦截)LGPD: menor de 16 anos (Lei Felca),持有人小于 16 岁依法不提供数据,勿重试
10016005422第三方(上游依法拦截)LGPD: menor de idade,持有人 16 到 17 岁依法不提供数据,勿重试
10016006428第三方(上游依法拦截)LGPD: idade nao verificavel - informe a data de nascimento para completar a verificacao,年龄无法核实平台已带出生日期补核验一次仍未通过,勿重试
10016010400调用方CNPJ 格式不合法(须 14 位数字)检查是否误传格式符
10016011400调用方CNPJ 校验位不合法本地先用 mod-11 算法校验
10016012400调用方未找到该 CNPJ 的信息该 CNPJ 在官方登记中不存在
10016020503第三方(上游不可用)上游数据源暂不可用指数退避重试(初始 1 秒,倍增至 30 秒上限,加抖动);持续出现请联系平台

处理指引

  • 401 / 403:配置错误;修正凭证、订阅或时钟。不要原样重试。
  • 400 / 404:请求或业务规则问题;按码修正。少数码为暂时性,可稍后重试:10004002、10017005 / 10017006、10019005 / 10019006。
  • 422 / 428 / 451:身份核验的法定拦截;重试无意义。
  • 429:先按 Retry-After 等待再重试,仍被拒再指数退避加抖动(初始 1 秒,倍增至 30 秒上限);不理会 429 持续重发会进入冷却,见限流与退避。
  • 503:按 Retry-After 重试同一请求或链接(10009037、10015304 / 10015305、10016020)。
  • 5xx:退避重试;持续失败请携带失败请求的 timestamp 与路径联系平台。
  • 统一响应体 errorType:1 API 错误、2 SEFAZ 驳回、3 系统异常(可重试)、4 字段校验失败(修正请求)。
  • 不要盲目重发被驳回的单据:Negada 与 REJECTED 是终态结论,先按 SEFAZ 原因处理。