Referencia
Códigos de error
Referencia consolidada de códigos de error de la Open API de TF Fiscal, agrupada por capa y dominio, con estado HTTP, escenario y tratamiento recomendado.
Formas de error
Los errores tienen tres formas según la capa que los produjo, vea Convenciones generales:
| Capa | HTTP | Forma | Campo del código |
|---|---|---|---|
| Gateway de la plataforma (autenticación, suscripción, límite de tasa, enlaces de descarga) | 401 / 403 / 404 / 429 / 503 | Sobre de la plataforma {success, errorType, code, message} | code (entero) |
| Empresas, NF-e, CT-e, DC-e, registro de webhook | 400 / 404 | Array [{codigo, mensagem}], una entrada por problema | codigo (string) |
| Verificación de NF-e y consulta de registro | 400 / 422 / 428 / 451 / 500 / 503 | Objeto plano {code, message} | code (entero) |
Los mensajes se localizan según las cabeceras Language / Accept-Language (portugués por defecto). Ramifique por los códigos, nunca por el texto del mensaje. En la forma array, GW001, CER0005, NFe0001, CTe0001, DCe0001 y DCe0000x conservan sus valores alfanuméricos; todos los demás valores de codigo son el código de error de la plataforma como string numérica.
Rangos de código por dominio:
| Rango | Dominio |
|---|---|
| 10001xxx | Validación de petición y fallos de la plataforma |
| 10003xxx | Empresa y certificado |
| 10004xxx | Emisión, cancelación y carta de corrección de NF-e |
| 10005xxx | Motor tributario |
| 10009xxx | Plataforma abierta (autenticación, suscripción, límite de tasa, webhooks, enlaces de descarga) |
| 10013xxx | Descarga de archivos |
| 10015xxx | Verificación de NF-e |
| 10016xxx | Consulta de registro (CNPJ / CPF) |
| 10017xxx | CT-e |
| 10019xxx | DC-e |
Gateway: autenticación y autorización
Forma de sobre de la plataforma, producida antes de que la petición llegue a la API. 401 y 403 son errores de configuración; reintentar sin corregir es inútil y puede activar el límite de tasa. Vea Autenticación para el esquema de firma.
| HTTP | code | Significado | Acción |
|---|---|---|---|
| 401 | 10009000 | Faltan cabeceras de firma (token / sign / timestamp) | Envíe las tres cabeceras en cada petición |
| 401 | 10009001 | Timestamp inválido o desfase de reloj superior a ±300 s | Sincronice el reloj (NTP); genere el timestamp en cada petición, nunca lo reutilice |
| 401 | 10009002 | Token inválido | Compruebe el app_secret; si se rotó, actualice la configuración |
| 401 | 10009003 | Firma no coincide | Recalcule la firma; vea la lista de comprobación en Autenticación |
| 403 | 10009004 | Aplicación deshabilitada | Contacte con la plataforma |
| 403 | 10009015 | Aplicación no efectiva (pendiente de aprobación o rechazada) | Espere la aprobación / contacte con la plataforma |
| 403 | 10009014 | Cuenta del integrador deshabilitada | Contacte con la plataforma |
| 403 | 10009005 | API no suscrita | Solicite la suscripción del endpoint llamado |
| 429 | 10009006 | Límite de tasa superado | Retroceda y reintente (empiece en 1 s, duplique hasta 30 s, añada jitter); los límites aplican por aplicación y por grupo de endpoints |
Los enlaces de descarga (linkDanfe, linkDownloadXml, linkDacce, nfeLinkXml, cteLinkDacte, dceLinkDace y similares) son peticiones GET planas sin cabeceras de firma; sus fallos son estados HTTP con el sobre de la plataforma, vea Descarga de archivos:
| HTTP | code | Significado | Acción |
|---|---|---|---|
| 401 | 10009035 | Enlace de descarga inválido (ruta alterada, token reutilizado o firma no coincidente) | Use el enlace exactamente como lo devolvió la API de consulta |
| 401 | 10009036 | Enlace de descarga caducado | Consulte de nuevo el documento para obtener un enlace nuevo |
| 503 | 10009037 | Archivo aún no listo (servicio de renderizado ocupado) | Reintente el mismo enlace tras Retry-After |
| 404 | 10013011 | Archivo no encontrado | Compruebe de dónde salió el enlace |
| 429 | 10013016 | Demasiadas descargas desde una misma IP mediante enlaces de callback | Reintente tras Retry-After |
Validación de petición y fallos de la plataforma
| code | HTTP | Forma | Escenario | Acción |
|---|---|---|---|---|
| 10001001 | 400 | Array | Falló la validación de campos de la petición, una entrada por campo; también errores de contrato de registro / actualización de la sección emissaoDCe (faltan los dos bloques de configuración, actualización que cambia cnpj / municipio, reducción del cursor de la serie, cambio de serie) | Corrija según mensagem |
| 10001000 | 500 | Objeto plano | Fallo del lado de la plataforma en una llamada de verificación o consulta de registro | Reintente con backoff; si persiste, contacte con la plataforma con el timestamp y el path de la petición |
Empresas y certificados
Forma array. Vea Empresas.
| codigo | HTTP | Escenario | Acción |
|---|---|---|---|
GW001 | 400 | Registro: ciudad / estado no se resuelven a un código IBGE; emisión: el código IBGE del municipio del destinatario no existe o es inconsistente con uf | Compruebe la UF y el nombre de la ciudad / código IBGE |
CER0005 | 400 | Contraseña del certificado incorrecta | Compruebe la contraseña |
| 10003000 | 404 | empresaId no existe o no pertenece a esta aplicación | Compruebe el empresaId |
| 10003002 | 400 | CNPJ ya registrado | La empresa existe; use el empresaId original |
| 10003006 | 400 | Datos de registro sin la IE | Indique inscricaoEstadual |
| 10003010 | 400 | El CNPJ del certificado no coincide con la empresa | Use el certificado correcto |
| 10003011 | 400 | Certificado caducado | Use un certificado válido |
| 10003012 | 400 | Certificado idéntico al actualmente activo | Nada que subir |
| 10009033 | 400 | Registro de webhook inválido (id no coincide / contentType no JSON) | Corrija según lo indicado, vea Registrar webhook |
NF-e
Forma array. Los errores de negocio son HTTP 400; un documento desconocido es HTTP 404 con codigo NFe0001. Los rechazos de SEFAZ durante la emisión no son errores HTTP: aparecen como estado Negada en la consulta y como webhook invoice.rejected. Vea NF-e.
| codigo | HTTP | Escenario | Acción |
|---|---|---|---|
NFe0001 | 404 | El nfeId de la consulta / cancelación / carta de corrección no existe | Compruebe el id enviado en la emisión y el empresaId |
| 10004002 | 400 | Demasiadas tareas de emisión pendientes para el CNPJ | Reintente más tarde |
| 10004004 | 400 | Empresa no apta para emitir (aún no aprobada o certificado no listo) | Espere la aprobación / vincule el certificado |
| 10004012 | 400 | Cancelación / carta de corrección: la factura no está autorizada | Consulte para confirmar el estado |
| 10004013 | 400 | Cancelación: fuera de la ventana de 24 horas | Emita una factura de devolución |
| 10004014 | 400 | Cancelación: rechazada por SEFAZ (código de estado y motivo adjuntos) | Actúe según el motivo de SEFAZ |
| 10004015 | 400 | Carta de corrección: ya hay 20 cartas registradas en la factura | Sin más cartas; cancele y reemita o emita factura de devolución |
| 10004016 | 400 | Carta de corrección rechazada por SEFAZ (código de estado y motivo adjuntos) | Actúe según el motivo de SEFAZ |
| 10004017 | 400 | Carta de corrección: menos de 15 caracteres tras la sanitización | Reescriba en portugués / ASCII |
| 10004019 | 400 | Carta de corrección: fuera de la ventana de 720 horas tras la autorización | Solo cancelar y reemitir o factura de devolución |
| 10004021 a 10004026 | 400 | Referencias de la factura de devolución: referencia ausente / referencia en una factura que no es de devolución / original no encontrada o de otra empresa / original no autorizada / ítem original no encontrado / cantidad superior a la línea original | Vea las reglas de factura de devolución en Emitir NF-e |
| 10004030 | 400 | ambienteEmissao no coincide con el entorno actual de la empresa | Envíe en el entorno de la empresa o pida a operaciones el cambio, vea Entornos |
| 10004031 | 400 | Valor no soportado (presencaConsumidor / varios pagos / tipo de pago desconocido / tipoPessoa inconsistente con el documento / comprador CPF con inscricaoEstadual) | Ajuste al alcance soportado en Emitir NF-e |
| 10004034 | 400 | Comprador CNPJ sin cliente.inscricaoEstadual | Envíe la inscripción estatal del comprador (contribuyente de ICMS) |
| 10004043 | 400 | Falta un campo de contrato (reducción de base / margen y tasa de ST / diferimiento / importe de impuesto por unidad / código de IPI / pCredSN ausente tanto en la petición como en el perfil); mensagem indica la ruta del campo | Complete el campo según la matriz de códigos tributarios en Emitir NF-e |
| 10004044 | 400 | Campo no aplicable al código tributario (substituicaoTributaria en un código sin ST, percentualCreditoSimples en un código sin crédito) | Elimine el grupo |
| 10004045 | 400 | El cliente.inscricaoEstadual del comprador CNPJ no cumple la regla de dígito verificador del estado del comprador (SEFAZ lo rechazaría con 209 tras la numeración) | Compruebe la IE y el estado del comprador |
| 10004046 | 400 | El código tributario no coincide con el régimen de la empresa (CRT 1/4 requiere CSOSN de 3 dígitos, CRT 2/3 CST de 2 dígitos) | Use la familia de códigos del régimen de la empresa |
| 10004047 | 400 | Comprador no contribuyente con un código exclusivo de contribuyente (10/30/70, 101/201/202/203) o con pCredSN | Use 102 / 500 o 900 sin crédito |
| 10005000 | 400 | Rechazado por el motor tributario (régimen / código tributario incompatible, código de ST para comprador no contribuyente, tasa fuera de rango) | Vea las reglas de parámetros tributarios en Emitir NF-e |
CT-e
Forma array. Los errores de negocio son HTTP 400; un documento / tarea inexistente es HTTP 404 con codigo CTe0001. Los rechazos de SEFAZ durante la emisión aparecen como estado Negada en la consulta y como webhook cte.rejected. Vea CT-e.
| codigo | HTTP | Escenario | Acción |
|---|---|---|---|
CTe0001 | 404 | cteId no encontrado o no pertenece a la empresa | Compruebe el id y el empresaId |
| 10003000 | 404 | empresaId no encontrado | Compruebe el empresaId |
| 10017004 | 400 | La empresa no puede emitir (no aprobada / certificado no listo) | Espere la aprobación / vincule el certificado |
| 10017005 / 10017006 | 400 | Petición duplicada concurrente / demasiadas tareas pendientes para el CNPJ | Reintente más tarde |
| 10017007 | 400 | Serie numérica sin resolver (ninguna configurada, o varias activas sin elección) | Configure una serie del modelo 57 |
| 10017010 | 400 | ambienteEmissao difiere del entorno de la empresa | Envíe para el entorno de la empresa |
| 10017011 | 400 | Código IBGE del municipio no encontrado | Compruebe codigoIbge |
| 10017012 / 10017013 | 400 | Falta un participante / tomador inconsistente con el indicador de IE | Añada el participante o cambie indicadorIeTomador |
| 10017014 | 400 | Referencias de documentos inválidas (ausentes, dígito verificador incorrecto, grupos mezclados, documentos previos inconsistentes con el tipo de servicio) | Ajuste las referencias |
| 10017015 | 400 | Tipo de documento inconsistente con las referencias (complementario / sustituto) | Envíe ctesComplementados / cteSubstituido según tipo |
| 10017016 | 400 | Los componentes no suman el total, o aReceber supera el total | Corrija los importes |
| 10017017 / 10017018 / 10017019 | 400 | RNTRC inválido / modal no soportado / enumeración o formato inválido (mensagem indica el campo) | Corrija según mensagem |
| 10017020 a 10017025 | 400 | Parámetro tributario ausente / no permitido / incompatible con el régimen / icmsUfFim obligatorio / falta la fila de la tabla de tasas / CST no soportado | Vea los parámetros tributarios en CT-e |
| 10017030 | 400 | Mismo id con un mensaje diferente | Use un id nuevo o reenvíe el mensaje original |
| 10017031 | 400 | Producción: ya existe un documento activo / autorizado para el id | Consulte el original |
| 10017040 a 10017045 | 400 | El estado no permite el evento / ventana de cancelación superada / texto de evento inválido / SEFAZ rechazó el evento / límite de secuencia de corrección / evento referenciado no encontrado | Vea las reglas de cancelación y eventos en CT-e |
| 10017048 / 10017049 | 400 | Cancelación bloqueada por una carta de corrección registrada / carta de corrección fuera de la ventana de 720 horas | Vea las reglas de cancelación y eventos en CT-e |
| 10001001 | 400 | Falló la validación de campos de la petición (una entrada por campo) | Corrija según mensagem |
DC-e
Forma array. Los errores de negocio son HTTP 400; un documento / tarea inexistente es HTTP 404 con codigo DCe0001. Los casos con código de ejemplo documentado conservan ese código; todos los demás codigo son el código numérico de la plataforma. Los rechazos de SEFAZ durante la emisión aparecen como estado Negada en la consulta y como webhook dce.rejected; los rechazos de la cancelación por SEFAZ aparecen como dce.cancel_rejected. Vea DC-e.
| codigo | HTTP | Escenario | Acción |
|---|---|---|---|
DCe0001 | 404 | dceId no encontrado, no pertenece a la empresa, o cancelación solicitada antes de materializar el documento | Compruebe el id y el empresaId; cancele documentos Pendente solo tras la autorización |
| 10003000 | 404 | empresaId no encontrado | Compruebe el empresaId |
DCe00004 | 400 | Empresa no configurada para DC-e (falta tipoEmitente / serie del modelo 99 / sitio de Marketplace), o ambiente difiere del entorno actual de la empresa | Envíe emissaoDCe en el registro o en una actualización con id; envíe para el entorno actual de la empresa y pida a operaciones el cambio a producción |
DCe00005 | 400 | Empresa Marketplace / Carrier sin remetente | Añada el remitente |
DCe00006 | 400 | Falta remetente.endereco | Añada la dirección del remitente |
DCe00007 | 400 | Remitente brasileño sin cpfCnpj | Añada el documento del remitente |
DCe00008 | 400 | La empresa no puede emitir (no aprobada / certificado no listo) | Espere la aprobación / vincule el certificado |
DCe00009 | 400 | Destinatario brasileño sin cpfCnpj | Añada el documento del destinatario |
GW001 | 400 | Código IBGE del municipio no encontrado o inconsistente con uf | Compruebe cidade / uf |
| 10019005 / 10019006 | 400 | Petición duplicada concurrente / demasiadas tareas pendientes para el CNPJ | Reintente más tarde |
| 10019007 | 400 | Serie numérica sin resolver (varias series activas) | Pida a operaciones que consolide las series |
| 10019013 | 400 | Tipo de emisor Carrier aún no soportado para emisión | Use una empresa Marketplace / OwnIssuer |
| 10019018 | 400 | Ítem inválido (longitud del NCM, cantidad ≤ 0, precio unitario negativo) | Corrija según mensagem |
| 10019019 | 400 | Enumeración o formato inválido (mensagem indica el campo: tipoPessoa, modalidade, dataEmissao, documentos, teléfono, e-mail, remetente de emisor propio distinto de la empresa) | Corrija según mensagem |
| 10019020 | 400 | CNPJ del transportista inválido | Corrija cnpjTransportadora |
| 10019021 | 400 | Información adicional demasiado larga | Acorte el texto |
| 10019022 | 400 | Cantidad o documento inválido en autorizacaoDownloadXml; contiene el propio CNPJ del emisor; documento duplicado | Corrija la lista |
| 10019030 | 400 | Mismo id con un mensaje diferente | Use un id nuevo o reenvíe el mensaje original |
| 10019031 | 400 | Producción: ya existe un documento activo / autorizado para el id | Consulte el original |
| 10019040 a 10019043 | 400 | El estado no permite la cancelación / ventana de 24 horas superada / cancelación ya aceptada / motivo inválido | Vea las reglas de cancelación en DC-e |
| 10019048 | 400 | dataEmissao fuera de la ventana permitida (más de 5 minutos adelante o más de 30 días atrás; mensagem trae los límites actuales) | Use la hora actual u omita dataEmissao |
| 10001001 | 400 | Falló la validación de campos de la petición (una entrada por campo); errores de contrato de registro / actualización de emissaoDCe | Corrija según mensagem |
Verificación de NF-e
Forma plana {code, message}, HTTP 400. La petición nunca llega a la validación. Vea Verificación de NF-e.
| code | Endpoint | Significado | Acción |
|---|---|---|---|
| 10015000 | Verificación de XML | Cuerpo de la petición vacío | Envíe el XML en el cuerpo |
| 10015001 | Verificación de XML | El cuerpo supera 1 MB | Una NF-e auténtica individual nunca supera ese tamaño; compruebe que no la está envolviendo ni codificando dos veces |
| 10015002 | Verificación de XML | DTD detectado (<!DOCTYPE) | Elimine los DTD; se rechazan como protección contra XXE |
| 10015003 | Verificación de XML | La codificación no es UTF-8 | Convierta a UTF-8 antes de enviar |
| 10015104 | Consulta por chave | Chave malformada (longitud / caracteres / dígito verificador) | Valide localmente primero: 44 dígitos; el último es un dígito verificador mod-11 |
| 10015004 | Consulta por chave | Factura no encontrada en ninguna fuente | La chave es desconocida para la plataforma y para la fuente oficial; confírmela con el emisor |
Errores de validación de nivel 1
Se devuelven con HTTP 200 dentro de validation.errors[] de la respuesta de la verificación de XML. No son errores de transporte: la petición tuvo éxito, el documento falló. Todos son bloqueantes (REJECTED terminal) salvo PROTOCOL_MISSING, que es un aviso.
errors[].code | Numérico | Significado |
|---|---|---|
XML_MALFORMED | 10015100 | Sintaxis XML inválida |
XSD_INVALID | 10015101 | No cumple el layout XSD de la NF-e 4.00 |
SIGNATURE_INVALID | 10015102 | Falló la verificación de la firma digital (contenido manipulado, o certificado caducado en el momento de firmar) |
SIGNATURE_CERT_MISMATCH | 10015103 | El CNPJ del certificado de firma no coincide con el emisor |
ACCESS_KEY_INVALID | 10015104 | Estructura / dígito verificador de la chave inválidos |
ACCESS_KEY_MISMATCH | 10015105 | Los segmentos de la chave no coinciden con los campos del documento |
PROTOCOL_MISMATCH | 10015106 | Bloque de protocolo inconsistente con el documento |
PROTOCOL_MISSING | 10015107 | Sin nodo de protocolo (aviso, no bloqueante) |
XML_VERSION_UNSUPPORTED | 10015108 | La versión del layout no es 4.00 |
Resultados de nivel 2
No son errores HTTP: llegan por el webhook invoice.verify.completed.
validationStatus | Terminal | Acción |
|---|---|---|
VALIDATED | Sí | Seguro continuar (liberar mercancía, liquidar) |
REJECTED | Sí | No continúe; reason explica el veredicto de SEFAZ (cancelada / denegada / inutilizada / no encontrada / protocolo divergente) |
VALIDATION_ERROR | No | Fallo de verificación del lado de la plataforma, no es un juicio sobre la factura; reenvíe más tarde con la cabecera forceRevalidate: true |
Consulta de registro
Forma plana {code, message}. Los errores de formato y de dígito verificador se rechazan localmente y nunca llegan a la fuente upstream; no consumen cuota y no se facturan. Vea Consulta de registro.
| code | HTTP | Responsable | Significado | Acción |
|---|---|---|---|---|
| 10016000 | 400 | Llamador | Formato de CPF inválido (se requieren 11 dígitos) | Compruebe caracteres de formato sobrantes o longitud incorrecta |
| 10016001 | 400 | Llamador | Dígitos verificadores del CPF inválidos | Valide localmente con el algoritmo mod-11 primero |
| 10016002 | 400 | Llamador | Fecha de nacimiento inválida (se requiere DDMMYYYY válido) | Observe el orden día-mes-año y que la fecha debe existir realmente |
| 10016003 | 400 | Llamador | CPF no encontrado | El CPF no existe, o el CPF y la fecha de nacimiento no coinciden (indistinguible a propósito) |
| 10016004 | 451 | Tercero (bloqueo legal upstream) | LGPD: menor de 16 anos (Lei Felca), el titular es menor de 16 años | Datos retenidos legalmente; no reintente |
| 10016005 | 422 | Tercero (bloqueo legal upstream) | LGPD: menor de idade, el titular tiene entre 16 y 17 años | Datos retenidos legalmente; no reintente |
| 10016006 | 428 | Tercero (bloqueo legal upstream) | LGPD: idade nao verificavel - informe a data de nascimento para completar a verificacao, no se puede verificar la edad | La plataforma ya reverificó una vez con la fecha de nacimiento; no reintente |
| 10016010 | 400 | Llamador | Formato de CNPJ inválido (se requieren 14 dígitos) | Compruebe caracteres de formato sobrantes |
| 10016011 | 400 | Llamador | Dígitos verificadores del CNPJ inválidos | Valide localmente con el algoritmo mod-11 primero |
| 10016012 | 400 | Llamador | CNPJ no encontrado | No existe ese CNPJ en el registro oficial |
| 10016020 | 503 | Tercero (upstream no disponible) | La fuente de datos upstream no está disponible temporalmente | Reintente con backoff exponencial (empiece en 1 s, duplique hasta 30 s, añada jitter); contacte con la plataforma si persiste |
Guía de tratamiento
- 401 / 403: errores de configuración; corrija la credencial, la suscripción o el reloj. No reintente tal cual.
- 400 / 404: la petición o la regla de negocio; corrija según el código. Algunos códigos son transitorios y pueden reintentarse más tarde: 10004002, 10017005 / 10017006, 10019005 / 10019006.
- 422 / 428 / 451: bloqueos legales en las consultas de registro; reintentar es inútil.
- 429: retroceda con retardo exponencial y jitter (empiece en 1 s, duplique hasta 30 s).
- 503: reintente la misma petición o enlace tras
Retry-After(10009037, 10016020). - 5xx: reintente con backoff; si persiste, contacte con la plataforma con el
timestampy el path de la petición. errorTypedel sobre:1error de API,2rechazo de SEFAZ,3fallo de sistema (reintentable),4fallo de validación de campos (corrija la petición).- Nunca reenvíe a ciegas un documento rechazado:
NegadayREJECTEDson veredictos terminales; actúe primero según el motivo de SEFAZ.