TF Fiscal
Documentación

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:

CapaHTTPFormaCampo del código
Gateway de la plataforma (autenticación, suscripción, límite de tasa, tamaño del cuerpo, enlaces de descarga)401 / 403 / 404 / 413 / 429 / 503Sobre de la plataforma {success, errorType, code, message}code (entero)
Empresas, NF-e, NFC-e, CT-e, DC-e, NFS-e, e-mail de facturas, registro de webhook400 / 404 / 409 / 500Array [{codigo, mensagem}], una entrada por problemacodigo (string)
Verificación de NF-e y consulta de registro400 / 404 / 409 / 422 / 428 / 451 / 500 / 503Objeto plano {code, message}code (entero)
Endpoints abiertos de NFC-e offline200 / 400 / 404Sobre de la plataforma; los errores de negocio también son HTTP 200code (entero)
Interfaz local del Asistente Fiscal400 / 404 / 409 / 429 / 500 / 503; autenticación 401 / 403Errores de negocio en array [{codigo, mensagem}]; errores de autenticación en sobre de la plataformacodigo / code
SDK embebidoningunoCodigo y Tipo del objeto de excepciónCodigo (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 todo codigo es el código de error de la plataforma como string numérica.

Rangos de código por dominio:

RangoDominio
10001xxxValidación de petición y fallos de la plataforma
10003xxxEmpresa y certificado
10004xxxEmisión, cancelación y carta de corrección de NF-e
10005xxxMotor tributario
10009xxxPlataforma abierta (autenticación, suscripción, límite de tasa, webhooks, enlaces de descarga)
10013xxxDescarga de archivos
10015xxxVerificación de NF-e
10016xxxConsulta de registro (CNPJ / CPF)
10017xxxCT-e
10018xxxNFS-e
10019xxxDC-e
10021xxxE-mail de facturas
10022xxxNFC-e
10029xxxNFC-e offline (endpoints abiertos, emparejamiento de dispositivos, núcleo de emisión offline, SDK, Asistente Fiscal)

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.

HTTPcodeSignificadoAcción
40110009000Faltan cabeceras de firma (token / sign / timestamp)Envíe las tres cabeceras en cada petición
40110009001Timestamp inválido o desfase de reloj superior a ±300 sSincronice el reloj (NTP); genere el timestamp en cada petición, nunca lo reutilice
40110009002Token inválidoCompruebe el app_secret; si se rotó, actualice la configuración
40110009003Firma no coincideRecalcule la firma; vea la lista de comprobación en Autenticación
40310009004Aplicación deshabilitadaContacte con la plataforma
40310009015Aplicación no efectiva (pendiente de aprobación o rechazada)Espere la aprobación / contacte con la plataforma
40310009014Cuenta del integrador deshabilitadaContacte con la plataforma
40310009005API no suscritaSolicite la suscripción del endpoint llamado
42910009006Límite de tasa superado, o la aplicación está en bloqueo temporalEspere el Retry-After y reintente; si sigue rechazado, retroceda exponencialmente (empiece en 1 s, duplique hasta 30 s, añada jitter); los límites aplican por aplicación y por grupo de endpoints, reglas y cabeceras en Límite de tasa y backoff
41310009027El cuerpo de la petición supera el límite de tamaño del gatewayEnvíe cuerpos más pequeños; en la verificación de NF-e, envíe una sola NF-e de hasta 1 MB

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:

HTTPcodeSignificadoAcción
40110009035Enlace de descarga inválido (ruta alterada, token reutilizado o firma no coincidente)Use el enlace exactamente como lo devolvió la API de consulta
40110009036Enlace de descarga caducadoConsulte de nuevo el documento para obtener un enlace nuevo
50310009037Archivo aún no listoReintente el mismo enlace tras Retry-After
40410013011Archivo no encontradoCompruebe de dónde salió el enlace
42910013016Demasiadas descargas desde una misma IP mediante enlaces de callbackReintente tras Retry-After

Validación de petición y fallos de la plataforma

codeHTTPFormaEscenarioAcción
10001001400ArrayFalló 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
10001000500Array u objeto planoFallo del lado de la plataforma; los endpoints de forma array, la verificación y la consulta de registro pueden devolverloReintente 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.

codigoHTTPEscenarioAcción
10003004400Registro: 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 ufCompruebe la UF y el nombre de la ciudad / código IBGE
10003008400Contraseña del certificado incorrectaCompruebe la contraseña
10003000404empresaId no existe o no pertenece a esta aplicaciónCompruebe el empresaId
10003002400CNPJ ya registradoLa empresa existe; use el empresaId original
10003006400Datos de registro sin la IEIndique inscricaoEstadual
10003010400El CNPJ del certificado no coincide con la empresaUse el certificado correcto
10003011400Certificado caducadoUse un certificado válido
10003012400Certificado idéntico al actualmente activoNada que subir
10003050400Registro automático: CNPJ no encontrado en los datos registrales públicosVerifique el CNPJ
10003051503Registro automático: datos registrales públicos no disponiblesRepita la misma solicitud más tarde
10003052400Régimen tributario de la empresa pendiente de confirmación (registro automático); no emite documentos nuevosEnvíe optanteSimplesNacional y mei en Registrar empresa con id
10003053400Registro automático: estado o municipio de la dirección no identificadoUse el endpoint de registro de empresa
10009033400Registro de webhook inválido (id no coincide / contentType no JSON / código desconocido en eventos)Corrija según lo indicado, vea Registrar webhook
10009010400URL de callback inválida; solo direcciones http / httpsUse una dirección pública https
10009013400URL de callback apunta a una red interna o reservadaUse una dirección pública
10009019400URL de callback demasiado largaAcorte la URL

Clases de impuesto

Formato de array. Clase inexistente es HTTP 404, modificación simultánea es HTTP 409, el resto HTTP 400. Todos los códigos en Clases de impuesto.

Código de errorHTTPEscenarioAcción
10005200404Código inexistente o eliminadoVerifique el código y empresaId
10005203400Código de tributación no admitidoCorrija según las tablas de códigos en Emitir NF-e
10005204400La clasificación no pertenece al CSTLos tres primeros dígitos de la clasificación deben ser el CST
10005206409Clase modificada al mismo tiempoConsulte de nuevo y reenvíe
10005208400codigo en el cuerpo de la creación o de la sustitución enteraQuite codigo: la plataforma genera el código, lo devuelve en la creación y después va en la ruta
10005210400Campo desconocido en el cuerpo; mensagem señala la rutaQuite el campo; los nombres válidos están en la página del endpoint
10005211400Dos filas del mismo grupo con la misma combinación de cenario, tipoPessoa y naoContribuinteJunte o quite una de las filas
10005212400Primer dígito del cfop de la fila distinto del escenarioAjuste el CFOP al escenario: salida 5 / 6 / 7, entrada 1 / 2 / 3
10005213400Número o booleano enviado como texto; mensagem señala la rutaEnvíe los números como número JSON y los booleanos como true / false
10005214400CFOP fuera del grupo: ISSQN solo con 5933, ICMS nunca con 5933Ajuste el CFOP al grupo
10005216400tipo distinto del actual en la actualizaciónEl tipo no cambia; cree otra clase
10005217400Clase NFCe con un campo que la emisión de NFC-e no tiene; mensagem señala la rutaQuite el campo, o cree una clase NFe
10005218400Grupo que el tipo no admite: issqn en NFe, ipi en NFCeQuite el grupo
10005219400Clase NFCe con escenario fuera de SaidaDentroEstado / PadraoAjuste el escenario
10004047400Fila de ICMS de no contribuyente o persona física con código solo de contribuyente (10, 30, 70, 101, 201, 202, 203) o percentualCreditoSimplesUse 102 / 500 u otro código, o quite la dimensión
10005008400Fila de PIS / COFINS 01 con aliquota distinta de la alícuota legal del régimen de PIS/COFINS configurado en la empresaUse la alícuota legal u omítala; vea «Régimen tributario» en Empresas
10004046400Código incompatible con el régimen de la empresa (CRT 1/4 exige CSOSN de 3 dígitos, CRT 2/3 CST de 2 dígitos)Ajuste el código al régimen de la empresa

NF-e

Forma array. Los errores de negocio son HTTP 400; un documento desconocido es HTTP 404 con codigo 10004000 o 10004001. 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.

codigoHTTPEscenarioAcción
10004000 / 10004001404El nfeId de la consulta / cancelación / carta de corrección no existeCompruebe el id enviado en la emisión y el empresaId
10004002400Demasiadas tareas de emisión pendientes para el CNPJReintente más tarde
10004004400Empresa no apta para emitir (aún no aprobada o certificado no listo)Espere la aprobación / vincule el certificado
10004012400Cancelación / carta de corrección: la factura no está autorizadaConsulte para confirmar el estado
10004013400Cancelación: fuera de la ventana de 24 horasEmita una factura de devolución
10004014400Cancelación: rechazada por SEFAZ (código de estado y motivo adjuntos)Actúe según el motivo de SEFAZ
10004015400Carta de corrección: ya hay 20 cartas registradas en la facturaSin más cartas; cancele y reemita o emita factura de devolución
10004016400Carta de corrección rechazada por SEFAZ (código de estado y motivo adjuntos)Actúe según el motivo de SEFAZ
10004017400Carta de corrección: menos de 15 caracteres tras la sanitizaciónReescriba en portugués / ASCII
10004019400Carta de corrección: fuera de la ventana de 720 horas tras la autorizaciónSolo cancelar y reemitir o factura de devolución
10004021 a 10004026400Referencias 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 originalVea las reglas de factura de devolución en Emitir NF-e
10004030400ambienteEmissao no coincide con el entorno actual de la empresaEnvíe en el entorno de la empresa o pida a operaciones el cambio, vea Entornos
10004031400Valor 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
10004034400Comprador CNPJ sin cliente.inscricaoEstadualEnvíe la inscripción estatal del comprador (contribuyente de ICMS)
10004043400Falta 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 campoComplete el campo según la matriz de códigos tributarios en Emitir NF-e
10004044400Campo no aplicable al código tributario (substituicaoTributaria en un código sin ST, percentualCreditoSimples en un código sin crédito)Elimine el grupo
10004045400El 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
10004046400El 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
10004047400Comprador no contribuyente con un código exclusivo de contribuyente (10/30/70, 101/201/202/203) o con pCredSNUse 102 / 500 o 900 sin crédito
10004051400Código IBGE ausente y no se pudo completar por el CEP: el CEP no está en la base, corresponde a más de un municipio o es de otro estadoEnvíe el código IBGE o verifique cep / uf
10005000400Rechazado 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
10005007400Empresa CRT 3 sin alícuota de PIS / COFINS en el CST 01 y sin régimen de PIS/COFINS configurado: la plataforma no puede completarlaEnvíe aliquota o configure el régimen en la consola, en «Datos tributarios»; vea Empresas
10005008400Empresa CRT 3 con alícuota de PIS / COFINS en el CST 01 distinta de la legal de su régimen de PIS/COFINSUse la alícuota legal u omítala; vea Empresas
10005202400La clase de impuesto referenciada en la línea no existe, fue eliminada o es de otra empresaVerifique classeImposto y empresaId, vea Clases de impuesto
10005215400Clase de otro tipo: la NF-e solo referencia clases NFe y la NFC-e solo clases NFCeReferencie una clase del tipo correcto
10005220400La clase referenciada está incompatible con el régimen actual de la empresa (IncompativelComRegime)Sustituya la clase entera por el régimen nuevo, vea Clases de impuesto
10001002400Línea con classeImposto que envía icms o issqn sin cfopEnvíe cfop en esa línea
10005209400La clase referenciada no tiene fila para esta factura en un grupo que la línea necesita (ICMS o ISSQN de la línea de servicio, PIS, COFINS); mensagem indica el grupo, el escenario, el tipo de cliente y si el comprador es no contribuyenteAgregue una fila a la clase, o envíe el grupo en la solicitud; vea el orden de elección en Clases de impuesto

NFC-e

Forma array. Los errores de negocio son HTTP 400; un documento o empresa desconocidos son HTTP 404. Los rechazos de SEFAZ no son errores HTTP: aparecen como estado Negada en la consulta y como webhook nfce.rejected. Vea NFC-e.

codigoHTTPEscenarioAcción
10022006404nfceId no existeRevise el id y el empresaId
10003000404empresaId no existeRevise el empresaId
10022001400NFC-e no habilitada en el ambiente actual de la empresaEnvíe ese ambiente en emissaoNFeConsumidor en el registro o la actualización
10022002400La empresa no puede emitir (no aprobada o certificado no disponible)Espere la aprobación o envíe el certificado
10022003400ambienteEmissao distinto del ambiente actual de la empresaEnvíe en el ambiente de la empresa
10022004400Infringe una regla de la NFC-e; mensagem indica cuálCorrija, o emita una NF-e
10022007400Plazo de cancelación vencido (30 minutos en la cancelación, 168 horas en la sustitución)Siga la regla del estado y emita una NF-e de reversión
10022008400El estado no lo permite (no autorizada, cancelación en curso)Consulte para confirmar el estado
10022009400El estado exige QR Code v2 y la empresa no tiene CSC utilizableEl QR Code v2 lo activa la plataforma y el CSC solo tiene efecto en producción; contacte a la plataforma
10022024400Código IBGE ausente y no se pudo completar por el CEP: el CEP no está en la base, corresponde a más de un municipio o es de otro estadoEnvíe el código IBGE o verifique cep / uf
10001001400Falló la validación de camposCorrija según mensagem
10005000400El motor tributario rechazó la solicitudCorrija según mensagem
10005007400Empresa CRT 3 sin alícuota de PIS / COFINS en el CST 01 y sin régimen de PIS/COFINS configurado: la plataforma no puede completarlaEnvíe aliquota o configure el régimen en la consola, en «Datos tributarios»; vea Empresas
10005008400Empresa CRT 3 con alícuota de PIS / COFINS en el CST 01 distinta de la legal de su régimen de PIS/COFINSUse la alícuota legal u omítala; vea Empresas
10005202400La clase de impuesto referenciada en la línea no existe, fue eliminada o es de otra empresaVerifique classeImposto y empresaId, vea Clases de impuesto
10005215400Clase de otro tipo: la NF-e solo referencia clases NFe y la NFC-e solo clases NFCeReferencie una clase del tipo correcto
10005220400La clase referenciada está incompatible con el régimen actual de la empresa (IncompativelComRegime)Sustituya la clase entera por el régimen nuevo, vea Clases de impuesto
10001002400Línea con classeImposto que envía icms o issqn sin cfopEnvíe cfop en esa línea
10005209400La clase referenciada no tiene fila para esta factura en un grupo que la línea necesita (ICMS o ISSQN de la línea de servicio, PIS, COFINS); mensagem indica el grupo, el escenario, el tipo de cliente y si el comprador es no contribuyenteAgregue una fila a la clase, o envíe el grupo en la solicitud; vea el orden de elección en Clases de impuesto
10005205400La fila elegida de la clase tiene un grupo o campo que la NFC-e no acepta; mensagem señala el campoCree una clase propia para la NFC-e, o envíe ese grupo en la solicitud

Motivos comunes de 10022004: presencia no permitida; lugar de entrega o retiro fuera del estado, o comprador contribuyente; importe por encima del límite; falta identificación; entrega sin transportista o dirección, o transportista o flete en una venta sin entrega; entrega no permitida en el estado; CFOP o código tributario fuera de la lista de la NFC-e; pago insuficiente, vuelto erróneo o SemPagamento, o terminal de tarjeta o descripción en un tipo de pago que no los acepta; campos que la NFC-e no acepta (todos listados a la vez); nombres de valor desconocidos.

Rechazos comunes de la SEFAZ (repetidos tal cual en motivoStatus): 704 emisión más de 5 minutos antes de la recepción por la SEFAZ; 717 presencia no permitida; 725 CFOP no permitido; 750 límite de identificación alcanzado sin identificar al consumidor; 780 por encima del límite del estado; 785 / 786 / 787 / 788 entrega no permitida en el estado, entrega sin transportista, sin consumidor, sin dirección; 462 / 463 / 464 CSC no registrado, revocado, QR Code no coincide; 865 pagos por debajo del total de la nota.

NFC-e offline

Vea NFC-e offline.

Endpoints abiertos

Sobre de la plataforma. Los errores de negocio son HTTP 200 con success = false; empresa o dispositivo inexistente es HTTP 404; la validación de campo es HTTP 400.

codigoHTTPEscenarioAcción
10029100404Empresa inexistente o de otro integradorRevise el empresaId
10029202404Dispositivo inexistente o de otra empresaRevise el dispositivoId
10029101200La empresa no puede emitir NFC-e: aún no aprobada por la plataforma, rechazada o desactivada, sin NFC-e habilitada en el ambiente elegido o sin certificado A1 válido en producción; message indica el motivoUna empresa recién registrada debe esperar la aprobación de la plataforma antes de habilitar la emisión offline y generar códigos de emparejamiento; si fue rechazada, corrija según el motivo y reenvíe; envíe emissaoNFeConsumidor en el registro; asocie un certificado válido
10029104200Emisión offline de la empresa desactivada por la plataformaContacte a la plataforma
10029201200La empresa ya tiene 20 códigos de emparejamiento pendientesÚselos o espere a que venzan
10029219200ambiente distinto del ambiente actual de la empresaGenere el código en el ambiente actual de la empresa
10029221200serie entre 890 y 999; la NFC-e de emisor CNPJ solo usa las series 0 a 889Use una serie de 0 a 889
10029222200serie es la serie NFC-e del perfil de la empresa en alguno de los ambientesElija otra serie
10029223200serie ya la tiene otro dispositivo activo o un código pendiente de la empresa; message dice cuálElija otra serie
10029224200numeroInicial no es mayor que el mayor número conocido en la serie; message trae ese númeroEnvíe un número inicial mayor, u omítalo para continuar después de ese número
10029225200serie pertenece a un dispositivo desactivado o revocado que aún tiene notas offline por transmitirGenere el código cuando el dispositivo anterior termine de transmitir
10029001200Valor de parámetro fuera de rango; message indica el campoCorrija según los valores permitidos
10001001400Validación de campos de la solicitudCorrija según message

Emparejamiento de dispositivos

Los devuelve la plataforma durante el emparejamiento por el Asistente Fiscal o por el SDK; el asistente de instalación y la excepción del SDK los muestran tal cual.

codigoEscenarioAcción
10029203 / 10029204Dispositivo desactivado / revocado por la plataformaGenere un nuevo código de emparejamiento
10029205Código de emparejamiento inválidoVerifique que se copió completo; si hace falta, genere otro
10029206 / 10029207 / 10029208Código de emparejamiento vencido / ya utilizado / anuladoGenere un nuevo código de emparejamiento
10029209El código no permite esta forma (por ejemplo, código Assistente usado en el SDK)Genere otro según la forma de integración
10029210Emparejamiento por SDK sin nombre del software de cajaInforme el nombre del software de caja al iniciar
10029501Software de caja bloqueado por la plataformaContacte a la plataforma
10029211Versión del PDV bloqueada o por debajo de la mínimaActualice el PDV
10029212Versión del núcleo obsoletaActualice el Asistente Fiscal o el SDK
10029213El CNPJ del certificado no coincide con el de la empresaUse el certificado A1 de la empresa
10029214Certificado vencidoUse un certificado válido
10029219Ambiente del código distinto del ambiente actual de la empresa (se verifica de nuevo en el emparejamiento)Genere un código nuevo en el ambiente actual de la empresa
10029221 a 10029225La serie del dispositivo indicada en el código se verifica de nuevo en el emparejamiento y ya no está disponible; mismo significado que al generar el códigoGenere un código nuevo con otra serie u otro número inicial
10029307Ambiente del dispositivo distinto del ambiente actual de la empresa: tras el cambio de ambiente, la emisión en línea y la transmisión del dispositivo anterior se rechazanGenere un código en el ambiente actual, empareje un dispositivo nuevo y desactive el anterior
10029424Número ya usado en la emisión en línea del dispositivo; se devuelve cuando el núcleo descartó el número, reintentó una vez y el conflicto sigueLa base local y los registros de la plataforma no coinciden; exporte los registros y contacte a la plataforma
10029426En la emisión en línea del dispositivo, el mismo id ya tiene una nota no rechazada en la plataformaVerifique la nota original; use un id nuevo para una venta nueva

Núcleo de emisión offline y SDK

El Asistente Fiscal y el SDK embebido comparten el núcleo de emisión offline. Sus errores llegan como excepción en el SDK (Codigo es el código y Tipo la constante) y como codigo en la interfaz local del Asistente Fiscal. Los rangos 10029800 y 10029780 vienen del núcleo y el rango 10029870 de la comunicación entre el SDK y el runtime; los códigos que solo aparecen por un defecto del propio SDK no se listan aquí, vea la Referencia del SDK. Los códigos que devuelve la plataforma se transmiten tal cual.

codigoConstanteEscenarioAcción
10029780ENGINE_TAX_CLASS_REQUIRES_ONLINEUn ítem referencia una clase de impuesto, pero no se pudo acceder a la plataforma para expandirla; no se consumió ningún número; el Asistente Fiscal devuelve HTTP 400Reenvíe con el mismo id cuando vuelva la red; sin red, envíe impostos en los ítems, vea Clases de impuesto y conexión
10029801ENGINE_NOT_ACTIVATEDLa empresa no está emparejada en este equipo, o el equipo aún no emparejó ninguna empresaGuíe el emparejamiento; con varias empresas revise empresaId
10029802ENGINE_EMPRESA_REQUIREDHay varias empresas emparejadas y no se indicó empresaIdEnvíe empresaId
10029803ENGINE_LICENSE_MISSINGNo hay licencia para emisión offlineSincronice en línea una vez (SincronizarAgora)
10029804ENGINE_LICENSE_EXPIREDLicencia vencida; la emisión offline se rechaza, la emisión en línea sigue normalRestablezca la red; se renueva sola
10029805ENGINE_LICENSE_SIGNATURE_INVALIDFirma de la licencia inválidaAtención manual: contacte a la plataforma, la base local puede haber sido alterada
10029806ENGINE_LICENSE_NOT_FOR_DEVICELa licencia no pertenece a este dispositivoAtención manual: empareje de nuevo
10029807ENGINE_OFFLINE_WINDOW_CLOSEDPasó el plazo de emisión offlineEmita en línea cuando vuelva la red
10029808ENGINE_LICENSE_QUOTA_EXHAUSTEDLa serie del dispositivo llegó al número 999999999Desactive el dispositivo y emparéjelo de nuevo con un código de emparejamiento nuevo que indique otra serie en serie; la plataforma no cambia la serie por sí sola
10029809ENGINE_CLOCK_ROLLBACKEl reloj del sistema retrocedióAtención manual: corrija la hora del sistema
10029810ENGINE_TRANSMISSION_DEADLINE_REACHEDLa nota pendiente más antigua superó el plazo de transmisiónAtención manual: restablezca la red cuanto antes para transmitir
10029811ENGINE_OFFLINE_NOT_ALLOWEDLa empresa o el estado no permite emisión offline; o se acaba de restaurar la copia de seguridad y aún no se obtuvo una licencia nuevaSolo emisión en línea; tras una restauración reciente, la emisión offline vuelve sola después de una sincronización en línea
10029812ENGINE_OFFLINE_FUEL_NOT_SUPPORTEDLas notas con combustible no se emiten offlineEmita cuando vuelva la red
10029813ENGINE_CERTIFICATE_UNAVAILABLECertificado no encontrado, sin clave privada o con CNPJ distintoAtención manual: revise el almacén de certificados; si hace falta, TrocarCertificado
10029814ENGINE_CERTIFICATE_EXPIREDCertificado vencidoAtención manual: renueve y llame TrocarCertificado
10029815ENGINE_SNAPSHOT_MISSINGFaltan la configuración local o los datos tributarios, o no pasaron la verificaciónSincronice en línea; si persiste, contacte a la plataforma
10029816ENGINE_DEVICE_DEACTIVATEDDispositivo desactivadoAtención manual: contacte al integrador; las notas offline ya emitidas se siguen transmitiendo
10029817ENGINE_REQUEST_INVALIDSolicitud inválida; Detalhes lista los motivos campo por campoCorrija la solicitud; puede validarla antes con Previsualizar
10029818ENGINE_DUPLICATE_ID_DIFFERENT_CONTENTEl mismo id ya se usó con contenido distintoVenta nueva con id nuevo; para reintentar, reenvíe la solicitud original y recupere la nota
10029819ENGINE_NOTE_NOT_FOUNDLa nota no existe en este equipoRevise id y empresaId
10029820ENGINE_NOTE_NOT_CORRECTABLEEl estado actual no permite corregirSolo Rejeitada admite Substituir
10029821ENGINE_CORRECTION_CHANGES_TOTALSLa corrección cambió valores o impuestosCambie solo lo que no afecta valores
10029822ENGINE_CANCEL_NOT_ALLOWEDEl estado actual no permite cancelar; en la cancelación por sustitución, la nota original no es una nota normal emitida en línea (nota offline, ya cancelada o con una cancelación pendiente)No reintente
10029823ENGINE_SERIE_EXHAUSTEDNumeración de la serie del dispositivo agotadaDesactive el dispositivo y emparéjelo de nuevo con un código de emparejamiento nuevo que indique otra serie en serie; la plataforma no cambia la serie por sí sola
10029824ENGINE_PLATFORM_UNREACHABLEUna operación que requiere conexión (emparejamiento) no llega a la plataformaRevise la red y reintente
10029825ENGINE_ACTIVATION_CODE_INVALIDFormato, firma o vigencia del código de emparejamiento incorrectosAtención manual: genere un código nuevo
10029826ENGINE_ACTIVATION_HOST_UNTRUSTEDEl código de emparejamiento apunta a una dirección de plataforma no confiableAtención manual: confirme el origen del código y el ambiente del instalador (pruebas / producción)
10029827ENGINE_KEY_PROTECTION_FAILEDEl directorio de datos viene de otra computadora o de otro usuario de WindowsAtención manual: ejecute en la computadora y el usuario originales, o empareje de nuevo
10029828ENGINE_DATA_DIR_LOCKEDEl directorio de datos está en uso por otro proceso, incluida, al restaurar una copia de seguridad, una instancia de este programa en la que todavía no se llamó EncerrarCierre la otra instancia; antes de restaurar una copia de seguridad, llame Encerrar
10029829ENGINE_LOCAL_STORE_CORRUPTEDBase local inconsistenteAtención manual: no borre el directorio de datos, contacte a la plataforma
10029830ENGINE_PROTOCOL_VERSION_UNSUPPORTEDVersiones de SDK y runtime incompatiblesActualice el SDK y el runtime juntos
10029831ENGINE_RUNTIME_START_FAILEDFalló el inicio del runtimeRevise que el directorio del runtime esté completo y que el antivirus no lo bloquee
10029832ENGINE_RUNTIME_CRASHEDEl runtime terminó inesperadamenteSe puede reintentar; con reinicio automático el SDK se recupera solo, reenvíe la emisión con el mismo id
10029833ENGINE_TIMEOUTTiempo de espera agotadoReenvíe la emisión con el mismo id, o primero Consultar
10029834ENGINE_SHUTTING_DOWNCerrando o ya cerradoLlame de nuevo Iniciar
10029835ENGINE_IN_PROCESS_UNSUPPORTEDEl modo en proceso de Java exige Java 21 o superiorUse el modo subproceso
10029836ENGINE_INTERNAL_ERRORError interno del núcleo; el mensaje trae un número de referenciaContacte a la plataforma con el número de referencia y los logs
10029837ENGINE_ALREADY_ACTIVATEDLa empresa ya está emparejada en este directorio de datosNo hace falta emparejar de nuevo; para cambiar de equipo, desactive antes el dispositivo anterior
10029838ENGINE_PLATFORM_RESPONSE_UNTRUSTEDRespuesta de la plataforma rechazada en la verificación; se conservaron los datos anterioresSe reintenta sola; si persiste, revise si un proxy de red altera las respuestas
10029839ENGINE_ACTIVATION_PERSIST_FAILEDLa plataforma emparejó pero falló el guardado localEmpareje de nuevo con el mismo código de emparejamiento
10029840ENGINE_CONFIG_INVALIDConfiguración de inicio inválidaCorrija la configuración
10029841ENGINE_AUTHORIZED_XML_UNAVAILABLEXML autorizado no disponible: aún no autorizado, o no está en este equipo y no se pudo recuperar de la plataformaEspere el evento de autorización y vuelva a pedirlo; si no se pudo recuperar, reintente más tarde
10029842ENGINE_LOCAL_STORE_NEWER_VERSIONEl directorio de datos fue usado por una versión más reciente y el núcleo se niega a iniciar; la interfaz local del Asistente Fiscal devuelve HTTP 503Instale o actualice a una versión no inferior a la última usada; no borre el directorio de datos
10029843ENGINE_CANCEL_XML_UNAVAILABLEXML de cancelación no disponible: aún no cancelada, o no está en este equipo y no se pudo recuperar de la plataformaEspere el evento de cancelación exitosa y vuelva a pedirlo; si no se pudo recuperar, reintente más tarde
10029844ENGINE_EXPORT_FAILEDFalló la escritura de la exportación o de la copia de seguridad: destino sin permiso de escritura, o el archivo de copia de seguridad ya existeCambie de directorio o de nombre de archivo; revise el espacio en disco y los permisos
10029845ENGINE_SUBSTITUTE_KEY_INVALIDLa clave de la nota sustituta en la cancelación por sustitución es inválida, o no es una nota offline no rechazada de este dispositivo y esta empresaEnvíe la clave de 44 dígitos de la nota offline emitida por este dispositivo para la misma venta
10029846ENGINE_BACKUP_INVALIDLa copia de seguridad no se puede restaurar: contraseña incorrecta, o el archivo de copia de seguridad fue modificado, está dañado o no es una copia de seguridad de la emisión offline; el Asistente Fiscal devuelve HTTP 400Verifique la contraseña de la copia de seguridad; use otra copia de seguridad íntegra. La base original queda sin cambios
10029874ENGINE_PARAMS_INVALIDParámetro ausente o de tipo incorrecto; Detalhes.campo indica cuálCorrija el parámetro, por ejemplo solicitud que no es objeto JSON, formato de la huella del certificado o de la fecha
10029877ENGINE_RUNTIME_NOT_FOUNDRuntime no encontradoRevise el instalador y el directorio del runtime
10029878ENGINE_TOO_MANY_PENDINGMás de 64 llamadas en espera al mismo tiempoReduzca la concurrencia
10029880ENGINE_PRINCIPAL_UNREACHABLEUn secundario en modo principal y secundario no alcanza al principal; la solicitud no llegóReintente más tarde, o pase la caja a la máquina de respaldo
10029881ENGINE_PRINCIPAL_RESULT_UNKNOWNLa solicitud llegó al principal pero no volvió respuesta; resultado desconocidoCuando vuelva el principal, consulte con el mismo id; reemitir con el mismo id y contenido no emite dos veces
10029882ENGINE_TERMINAL_TOKEN_INVALIDToken del terminal secundario inválido o revocadoEmita otro token en el principal y actualice la configuración del secundario
10029883ENGINE_PRINCIPAL_ADDRESS_INVALIDDirección del principal mal formada o fuera de la red local privadaCorrija la dirección del principal en la configuración del secundario
10029884ENGINE_MODE_METHOD_UNAVAILABLEEl modo actual no ofrece este métodoEmparejamiento, cambio de certificado, copia de seguridad y exportación se hacen en el principal; la gestión de terminales solo en el principal
10029885ENGINE_PRINCIPAL_REJECTEDEl principal rechazó el origen de la solicitud, por ejemplo un secundario fuera de las redes permitidasRevise las redes permitidas del principal y la red
10029886ENGINE_PRINCIPAL_RATE_LIMITEDDemasiados fallos de autenticación; limitado por el principalRevise el token y reintente tras 1 minuto
10029887ENGINE_PRINCIPAL_LISTEN_FAILEDNo se puede escuchar en el puerto de red local del principalCambie el puerto del principal o libere el puerto
10029888ENGINE_TERMINAL_NOT_FOUNDEl terminal a revocar no existeRevise el identificador del terminal

Asistente Fiscal

codigoHTTPEscenarioAcción
10029900401Falta el token de cajaEnvíe Authorization: Bearer tfl_…
10029901401Token de caja inválido o revocadoEl gerente genera un token nuevo
10029902403El token no tiene acceso a esa empresaGenere un token que incluya esa empresa
10029903403La dirección de origen no está en la red permitida del modo red localRevise la configuración del modo red local
10029904400Dirección de callback inválidaSolo http / https; con el modo red local desactivado, solo la dirección de loopback
10029905401La acción del programa de escritorio exige sesión de gerenteInicie sesión con el PIN de gerente
10029906401PIN de gerente incorrectoEscríbalo de nuevo; 5 errores en total lo bloquean
10029907409Impresora no disponibleRevise la conexión de la impresora y la impresora elegida en Configuración
10029908409Asistente de instalación no terminadoTermine primero el asistente de instalación
10029909400Solicitud inválidaCorrija según mensagem
10029910404Recurso inexistenteRevise la ruta
10029911400Formato de PIN inválido; debe tener de 6 a 8 dígitosDefínalo de nuevo con ese formato
10029912500Error interno del asistenteExporte el paquete de diagnóstico y contacte a la plataforma
10029913403Cabecera Host de la solicitud del programa de escritorio no permitida; solo 127.0.0.1, localhost o [::1] con el puerto del asistenteAbra el programa de escritorio en http://127.0.0.1:puerto, sin proxy ni otro nombre de host
10029914429Demasiados errores de PIN; bloqueadoEspere al fin del bloqueo, vea las preguntas frecuentes del Asistente Fiscal
10029916409Puerto elegido ocupado o sin poder escuchar; configuración sin cambiosElija otro puerto
10029917403La sesión de cajero no tiene acceso a esta empresaInicie sesión con el PIN de gerente para hacerlo
10029918429Asistente ocupado: ya hay 3 recuperaciones de XML en curso, o ya hay una exportación o una copia de seguridad en cursoReintente más tarde, sin repetir llamadas seguidas
10029919400Configuración del proxy de salida inválidaEn «Configuración» del programa de escritorio, corrija «Conexión a internet» y «Dirección» del proxy de salida según el aviso; la configuración no se guardó
10029920409Al guardar el proxy de salida o al restaurar desde una copia de seguridad hay que reiniciar el núcleo de emisión, pero hay una exportación, una copia de seguridad o una descarga de XML en curso que no terminó en 15 segundosEspere a que terminen esas operaciones y vuelva a guardar o a restaurar; ni la configuración ni la base local se modificaron
10029922409El disco donde está el directorio de datos del asistente tiene menos de 256 MB libres; se rechazó la exportación, la copia de seguridad o la carga del archivo de copia de seguridadLibere espacio en ese disco y reintente
10029923403La solicitud del programa de escritorio no trae el token anti-CSRF o lo trae incorrecto; suele ocurrir cuando la sesión expiró o la página quedó abierta demasiado tiempoRecargue la página; si persiste, vuelva a iniciar sesión con el PIN del gerente
10029924429Se abren sesiones de cajero con demasiada frecuencia: como máximo 20 por minuto desde el mismo origenEspere un minuto y vuelva a entrar en la página de emisión

Los errores del Asistente Fiscal solo aparecen en la interfaz local del asistente y en el programa de escritorio; el SDK embebido no los devuelve; de 10029905 a 10029908, 10029911, de 10029913 a 10029917 y de 10029919 a 10029924 solo aparecen en el programa de escritorio.

CT-e

Forma array. Los errores de negocio son HTTP 400; un documento / tarea inexistente es HTTP 404 con codigo 10017002 o 10017003. Los rechazos de SEFAZ durante la emisión aparecen como estado Negada en la consulta y como webhook cte.rejected. Vea CT-e.

codigoHTTPEscenarioAcción
10017002 / 10017003404cteId no encontrado o no pertenece a la empresaCompruebe el id y el empresaId
10003000404empresaId no encontradoCompruebe el empresaId
10017004400La empresa no puede emitir (no aprobada / certificado no listo)Espere la aprobación / vincule el certificado
10017005 / 10017006400Petición duplicada concurrente / demasiadas tareas pendientes para el CNPJReintente más tarde
10017007400Serie numérica sin resolver (ninguna configurada, o varias activas sin elección)Configure una serie del modelo 57
10017010400ambienteEmissao difiere del entorno de la empresaEnvíe para el entorno de la empresa
10017011400Código IBGE del municipio no encontradoCompruebe codigoIbge
10017050400codigoIbge ausente y no se pudo completar por el CEP: cep ausente, fuera de la base o corresponde a más de un municipioEnvíe codigoIbge o verifique cep
10017012 / 10017013400Falta un participante / tomador inconsistente con el indicador de IEAñada el participante o cambie indicadorIeTomador
10017014400Referencias de documentos inválidas (ausentes, dígito verificador incorrecto, grupos mezclados, documentos previos inconsistentes con el tipo de servicio)Ajuste las referencias
10017015400Tipo de documento inconsistente con las referencias (complementario / sustituto)Envíe ctesComplementados / cteSubstituido según tipo
10017016400Los componentes no suman el total, o aReceber supera el totalCorrija los importes
10017017 / 10017018 / 10017019400RNTRC inválido / modal no soportado / enumeración o formato inválido (mensagem indica el campo)Corrija según mensagem
10017020 a 10017025400Parámetro tributario ausente / no permitido / incompatible con el régimen / icmsUfFim obligatorio / falta la fila de la tabla de tasas / CST no soportadoVea los parámetros tributarios en CT-e
10017030400Mismo id con un mensaje diferenteUse un id nuevo o reenvíe el mensaje original
10017031400Producción: ya existe un documento activo / autorizado para el idConsulte el original
10017040 a 10017045400El 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 encontradoVea las reglas de cancelación y eventos en CT-e
10017048 / 10017049400Cancelación bloqueada por una carta de corrección registrada / carta de corrección fuera de la ventana de 720 horasVea las reglas de cancelación y eventos en CT-e
10001001400Falló 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 10019002 o 10019003. 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.

codigoHTTPEscenarioAcción
10019002 / 10019003404dceId no encontrado, no pertenece a la empresa, o cancelación solicitada antes de materializar el documentoCompruebe el id y el empresaId; cancele documentos Pendente solo tras la autorización
10003000404empresaId no encontradoCompruebe el empresaId
10019012 / 10019010400Empresa no configurada para DC-e (falta tipoEmitente / serie del modelo 99 / sitio de Marketplace), o ambiente difiere del entorno actual de la empresaEnví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
10019014400Empresa Marketplace / Carrier sin remetenteAñada el remitente
10019015400Falta remetente.enderecoAñada la dirección del remitente
10019016400Remitente brasileño sin cpfCnpjAñada el documento del remitente
10019004400La empresa no puede emitir (no aprobada / certificado no listo)Espere la aprobación / vincule el certificado
10019017400Destinatario brasileño sin cpfCnpjAñada el documento del destinatario
10019011400Código IBGE del municipio no encontrado o inconsistente con ufCompruebe cidade / uf
10019049400Código IBGE ausente y no se pudo completar por el CEP: el CEP no está en la base, corresponde a más de un municipio o es de otro estadoEnvíe el código IBGE o verifique cep / uf
10019005 / 10019006400Petición duplicada concurrente / demasiadas tareas pendientes para el CNPJReintente más tarde
10019007400Serie numérica sin resolver (varias series activas)Pida a operaciones que consolide las series
10019013400Tipo de emisor Carrier aún no soportado para emisiónUse una empresa Marketplace / OwnIssuer
10019018400Ítem inválido (longitud del NCM, cantidad ≤ 0, precio unitario negativo)Corrija según mensagem
10019019400Enumeració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
10019020400CNPJ del transportista inválidoCorrija cnpjTransportadora
10019021400Información adicional demasiado largaAcorte el texto
10019022400Cantidad o documento inválido en autorizacaoDownloadXml; contiene el propio CNPJ del emisor; documento duplicadoCorrija la lista
10019030400Mismo id con un mensaje diferenteUse un id nuevo o reenvíe el mensaje original
10019031400Producción: ya existe un documento activo / autorizado para el idConsulte el original
10019040 a 10019043400El estado no permite la cancelación / ventana de 24 horas superada / cancelación ya aceptada / motivo inválidoVea las reglas de cancelación en DC-e
10019048400dataEmissao 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
10001001400Falló la validación de campos de la petición (una entrada por campo); errores de contrato de registro / actualización de emissaoDCeCorrija según mensagem

NFS-e

Formato de array [{codigo, mensagem}]; los errores de negocio son HTTP 400 y un documento inexistente es HTTP 404 con codigo 10018002 o 10018003. La emisión es asíncrona: el rechazo en la aceptación es un error HTTP síncrono, mientras que el rechazo de la autoridad aparece como consulta Negada más el webhook nfse.rejected. Vea NFS-e.

codigoHTTPEscenarioQué hacer
10018001400Validación de parámetros rechazada en la aceptación; mensagem indica el motivo (control de IBS/CBS aún no vigente, emisor paulistano enviando ibsCbs, código o restricción estructural no satisfecha)Corrija según la mensagem
10018002 / 10018003404Documento no encontrado: el nfseId no pertenece a este emisor, o la clave de entrada no está entre sus facturas recibidasCoteje nfseId / chaveAcesso con empresaId
10018004400Emisor no apto (desactivado / certificado inutilizable)Revise el estado del emisor y el certificado
10018005400Emisor sin perfil de NFS-e; la mensagem señala el dato que faltaEnvíe emissaoNFSe en el registro o actualice con id
10018010400El estándar de NFS-e del municipio aún no está admitidoEse municipio todavía no puede emitir, contacte con la plataforma
10018012400Código de servicio fuera de la lista oficial LC 116Coteje codigoTributacaoNacional
10018013400Documento del receptor inválidoCoteje el CPF / CNPJ / NIF
10018014400Exportación de servicio sin país de destinoInforme servico.paisPrestacao
10018015400El documento sustituido no puede sustituirseRevise el estado del documento sustituido
10018020400No se pudo determinar la alícuota del ISS (sin valor informado ni parámetro municipal)Envíe servico.iss.aliquota o el servico.codigoTributacaoMunicipal correcto
10018022400Un emisor del Simples no puede enviar la alícuota de ISS directamenteQuite aliquota
10018023400La retención federal no puede determinarse; informe lo siguiente o envíe los valores retenidos: %s. %s lista de una vez las rutas de todos los campos que faltan: servico.retencoes.categoriaFederal, cliente.orgaoPublico, cliente.optanteSimplesNacional, servico.retencoes.modoContratacao, servico.retencoes.anexoSimples, servico.retencoes.inss/irrf/csll/pis/cofinsInforme los campos listados y reenvíe, o envíe los importes retenidos en servico.retencoes, cero cuando no haya; si la lista cita servico.retencoes.inss/irrf/csll/pis/cofins, solo los importes lo resuelven, caso de clasificación del servicio que exige análisis manual o de emisión por esta empresa como tomadora o intermediaria
10018030 / 10018031400La misma solicitud ya se está procesando / ese pedido ya tiene factura o el mismo id trae contenido distintoReintente más tarde; use otro número de pedido o coteje el contenido
10018040400Ya hay un análisis de cancelación en cursoEspere el veredicto del municipio
10018041400El documento ya fue sustituidoNo se permite ninguna otra operación
10018042400El estado actual no permite este evento (cancelación; manifestación: cancelada / sustituida / ya manifestada / este emisor no es receptor ni intermediario)Revise el estado; cada parte manifiesta una vez por factura
10018063400El mensaje del DPS no cumple el XSD oficial; el detalle trae línea, columna, clave del error y nombre del elementoSuele ser texto fuera de Latin-1, dirección incompleta, o un valor fuera de la tabla oficial
10018064400El mensaje de evento de la NFS-e no cumple el XSD oficialRevise la longitud de motivo (15-255), el valor de codigoMotivo y el juego de caracteres
10018065400Los datos de referencia fiscal de la NFS-e que necesita esta nota no se han importado; envíe en la solicitud los campos tras la flecha o importe primero los datos de referencia: %s. %s lista cada elemento con una flecha hacia el campo de la solicitud que lo sustituye: retencao-federal -> servico.retencoes.inss/irrf/csll/pis/cofins, pis-cofins -> servico.pisCofins.aliquotaPis/aliquotaCofins, iss-local-incidencia -> servico.iss.municipioIncidencia.codigoIbge; solo ocurre cuando un elemento que la solicitud no trajo debe consultarlo la plataforma, y siempre en la aceptaciónEnvíe en la solicitud los campos tras la flecha, o confirme con la plataforma que los datos están importados; iss-local-incidencia aparece con el lugar de la prestación en otro municipio, y basta con enviar servico.iss.municipioIncidencia
10018066400Código IBGE ausente y no se pudo completar por el CEP: el CEP no está en la base, corresponde a más de un municipio o es de otro estadoEnvíe el código IBGE o verifique cep / uf

E-mail de facturas

Forma array. Los errores de negocio son HTTP 400; no encontrado es HTTP 404; un correo anterior de la misma factura aún no finalizado es HTTP 409. Un fallo de envío no es un error HTTP: aparece como estado Falha en la consulta y como webhook email.failed. Vea E-mail de facturas.

CódigoHTTPCasoAcción
10003000404empresaId inexistenteCompruebe el empresaId
10021001404Plantilla de correo inexistente o de otro integradorCompruebe el templateId
10021002400Plantilla desactivada, o su tipo de documento difiere de la facturaUse otra plantilla o actívela
10021003400La plantilla usa una variable fuera de la lista permitidaCorrija según la enumeración de variables
10021004400HTML de la plantilla con contenido prohibido o cuerpo de más de 64 KBCorrija en los puntos que indica el mensaje
10021005400tipoDocumento no soportado en la lista de plantillasEnvíe solo NFe / NFSe / CTe / DCe
10021010404Factura inexistente o de otra empresaCompruebe documentoId, tipoDocumento y empresaId
10021011400Factura aún no autorizada, o cancelada o sustituidaEnvíe tras la autorización
10021012400Sin plantilla predeterminada para este tipo de documentoEnvíe templateId o defina una plantilla predeterminada
10021013400Sin destinatarioEnvíe destinatarios
10021015409El correo anterior de esta factura aún no terminóEspere Enviado o Falha y reenvíe con un nuevo id
10021020404Correo inexistente o de otra empresaCompruebe emailId y empresaId
10001001400Falló la validación de campos de la petición (una entrada por campo)Corrija según mensagem

Verificación de NF-e

Forma plana {code, message}, vea Verificación de NF-e. Los errores de petición de la verificación de XML y de la consulta por chave son HTTP 400; la petición nunca llega a la validación:

codeEndpointSignificadoAcción
10015000Verificación de XMLCuerpo de la petición vacíoEnvíe el XML en el cuerpo
10015001Verificación de XMLEl cuerpo supera 1 MBUna NF-e auténtica individual nunca supera ese tamaño; compruebe que no la está envolviendo ni codificando dos veces
10015002Verificación de XMLDTD detectado (<!DOCTYPE)Elimine los DTD
10015003Verificación de XMLLa codificación no es UTF-8Convierta a UTF-8 antes de enviar
10015005Verificación de XMLRetirado, ya no se devuelve (antes: chave ya enviada para verificación por otro integrador)Ninguna acción necesaria: cada integrador puede verificar la misma factura de forma independiente
10015104Consulta por chaveChave malformada (longitud / caracteres / dígito verificador)Valide localmente primero: 44 dígitos; el último es un dígito verificador mod-11
10015004Consulta por chaveFactura no encontrada en ninguna fuenteLa chave es desconocida para la plataforma y para la fuente oficial; confírmela con el emisor

Obtención del DANFE

Los fallos de la obtención del DANFE devuelven el estado HTTP de la tabla y un objeto plano {code, message}; los errores llegan en JSON aunque la petición lleve Accept: application/pdf.

codeHTTPSignificadoAcción
10015104400Chave malformada (longitud / caracteres / dígito verificador)Valide localmente primero: 44 dígitos; el último es un dígito verificador mod-11
10015300404Su cuenta no tiene registro de verificación de esta factura (la verificación hecha por otro integrador no cuenta)Envíela antes por la verificación de XML; no reintente
10015301409Verificación aún no terminada (PENDING_SEFAZ / VALIDATING)Obtenga el PDF después de recibir invoice.verify.completed
10015302409El veredicto actual no genera PDF (solo lo generan VALIDATED y las facturas con status Cancelada)No reintente
10015303409La plataforma no tiene el XML original de esta facturaReenvíe el mismo XML sin cambios por la verificación de XML, sin forceRevalidate, y vuelva a obtenerlo
10015304503El XML original aún se está archivandoReintente tras el Retry-After (5 segundos)
10015305503Generación ocupada o temporalmente no disponibleReintente tras el Retry-After
10001000500Error interno de la plataformaReintente con backoff; si persiste, contacte con la plataforma con el timestamp y el path de la petición

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[].codeNuméricoSignificado
XML_MALFORMED10015100Sintaxis XML inválida
XSD_INVALID10015101No cumple el layout XSD de la NF-e 4.00
SIGNATURE_INVALID10015102Falló la verificación de la firma digital (contenido manipulado, o certificado caducado en el momento de firmar)
SIGNATURE_CERT_MISMATCH10015103El CNPJ del certificado de firma no coincide con el emisor
ACCESS_KEY_INVALID10015104Estructura / dígito verificador de la chave inválidos
ACCESS_KEY_MISMATCH10015105Los segmentos de la chave no coinciden con los campos del documento
PROTOCOL_MISMATCH10015106Bloque de protocolo inconsistente con el documento
PROTOCOL_MISSING10015107Sin nodo de protocolo (aviso, no bloqueante)
XML_VERSION_UNSUPPORTED10015108La versión del layout no es 4.00

Resultados de nivel 2

No son errores HTTP: llegan por el webhook invoice.verify.completed.

validationStatusTerminalAcción
VALIDATEDSíSeguro continuar (liberar mercancía, liquidar)
REJECTEDSíNo continúe; reason explica el veredicto de SEFAZ (cancelada / denegada / inutilizada / no encontrada / protocolo divergente)
VALIDATION_ERROR (status null)Sí, reintentableFallo de verificación del lado de la plataforma, no es un juicio sobre la factura; como cualquier veredicto, se reutiliza durante 24 horas, así que reenvíe más tarde con la cabecera forceRevalidate: true
VALIDATION_ERROR (status Desconhecida)Sí, reintentar no lo cambiaráLa SEFAZ no acepta consultas de esta factura (por ejemplo, cStat 526, emitida hace demasiado tiempo); no es un juicio sobre la factura ni significa que sea falsa. El veredicto se reutiliza, no hace falta reintentar; confírmelo por otros medios si es necesario

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.

codeHTTPResponsableSignificadoAcción
10016000400LlamadorFormato de CPF inválido (se requieren 11 dígitos)Compruebe caracteres de formato sobrantes o longitud incorrecta
10016001400LlamadorDígitos verificadores del CPF inválidosValide localmente con el algoritmo mod-11 primero
10016002400LlamadorFecha de nacimiento inválida (se requiere DDMMYYYY válido)Observe el orden día-mes-año y que la fecha debe existir realmente
10016003400LlamadorCPF no encontradoEl CPF no existe, o el CPF y la fecha de nacimiento no coinciden (indistinguible a propósito)
10016004451Tercero (bloqueo legal upstream)LGPD: menor de 16 anos (Lei Felca), el titular es menor de 16 añosDatos retenidos legalmente; no reintente
10016005422Tercero (bloqueo legal upstream)LGPD: menor de idade, el titular tiene entre 16 y 17 añosDatos retenidos legalmente; no reintente
10016006428Tercero (bloqueo legal upstream)LGPD: idade nao verificavel - informe a data de nascimento para completar a verificacao, no se puede verificar la edadLa plataforma ya reverificó una vez con la fecha de nacimiento; no reintente
10016010400LlamadorFormato de CNPJ inválido (se requieren 14 dígitos)Compruebe caracteres de formato sobrantes
10016011400LlamadorDígitos verificadores del CNPJ inválidosValide localmente con el algoritmo mod-11 primero
10016012400LlamadorCNPJ no encontradoNo existe ese CNPJ en el registro oficial
10016020503Tercero (upstream no disponible)La fuente de datos upstream no está disponible temporalmenteReintente 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: espere el Retry-After y reintente; si sigue rechazado, retroceda con retardo exponencial y jitter (empiece en 1 s, duplique hasta 30 s); ignorar el 429 y reenviar sin parar lleva a un bloqueo temporal, vea Límite de tasa y backoff.
  • 503: reintente la misma petición o enlace tras Retry-After (10009037, 10015304 / 10015305, 10016020).
  • 5xx: reintente con backoff; si persiste, contacte con la plataforma con el timestamp y el path de la petición.
  • errorType del sobre: 1 error de API, 2 rechazo de SEFAZ, 3 fallo de sistema (reintentable), 4 fallo de validación de campos (corrija la petición).
  • Nunca reenvíe a ciegas un documento rechazado: Negada y REJECTED son veredictos terminales; actúe primero según el motivo de SEFAZ.