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, tamaño del cuerpo, enlaces de descarga) | 401 / 403 / 404 / 413 / 429 / 503 | Sobre 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 webhook | 400 / 404 / 409 / 500 | Array [{codigo, mensagem}], una entrada por problema | codigo (string) |
| Verificación de NF-e y consulta de registro | 400 / 404 / 409 / 422 / 428 / 451 / 500 / 503 | Objeto plano {code, message} | code (entero) |
| Endpoints abiertos de NFC-e offline | 200 / 400 / 404 | Sobre de la plataforma; los errores de negocio también son HTTP 200 | code (entero) |
| Interfaz local del Asistente Fiscal | 400 / 404 / 409 / 429 / 500 / 503; autenticación 401 / 403 | Errores de negocio en array [{codigo, mensagem}]; errores de autenticación en sobre de la plataforma | codigo / code |
| SDK embebido | ninguno | Codigo y Tipo del objeto de excepción | Codigo (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:
| 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 |
| 10018xxx | NFS-e |
| 10019xxx | DC-e |
| 10021xxx | E-mail de facturas |
| 10022xxx | NFC-e |
| 10029xxx | NFC-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.
| 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, o la aplicación está en bloqueo temporal | Espere 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 |
| 413 | 10009027 | El cuerpo de la petición supera el límite de tamaño del gateway | Enví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:
| 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 | 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 | Array u objeto plano | Fallo del lado de la plataforma; los endpoints de forma array, la verificación y la consulta de registro pueden devolverlo | 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 |
|---|---|---|---|
| 10003004 | 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 |
| 10003008 | 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 |
| 10003050 | 400 | Registro automático: CNPJ no encontrado en los datos registrales públicos | Verifique el CNPJ |
| 10003051 | 503 | Registro automático: datos registrales públicos no disponibles | Repita la misma solicitud más tarde |
| 10003052 | 400 | Régimen tributario de la empresa pendiente de confirmación (registro automático); no emite documentos nuevos | Envíe optanteSimplesNacional y mei en Registrar empresa con id |
| 10003053 | 400 | Registro automático: estado o municipio de la dirección no identificado | Use el endpoint de registro de empresa |
| 10009033 | 400 | Registro de webhook inválido (id no coincide / contentType no JSON / código desconocido en eventos) | Corrija según lo indicado, vea Registrar webhook |
| 10009010 | 400 | URL de callback inválida; solo direcciones http / https | Use una dirección pública https |
| 10009013 | 400 | URL de callback apunta a una red interna o reservada | Use una dirección pública |
| 10009019 | 400 | URL de callback demasiado larga | Acorte 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 error | HTTP | Escenario | Acción |
|---|---|---|---|
| 10005200 | 404 | Código inexistente o eliminado | Verifique el código y empresaId |
| 10005203 | 400 | Código de tributación no admitido | Corrija según las tablas de códigos en Emitir NF-e |
| 10005204 | 400 | La clasificación no pertenece al CST | Los tres primeros dígitos de la clasificación deben ser el CST |
| 10005206 | 409 | Clase modificada al mismo tiempo | Consulte de nuevo y reenvíe |
| 10005208 | 400 | codigo en el cuerpo de la creación o de la sustitución entera | Quite codigo: la plataforma genera el código, lo devuelve en la creación y después va en la ruta |
| 10005210 | 400 | Campo desconocido en el cuerpo; mensagem señala la ruta | Quite el campo; los nombres válidos están en la página del endpoint |
| 10005211 | 400 | Dos filas del mismo grupo con la misma combinación de cenario, tipoPessoa y naoContribuinte | Junte o quite una de las filas |
| 10005212 | 400 | Primer dígito del cfop de la fila distinto del escenario | Ajuste el CFOP al escenario: salida 5 / 6 / 7, entrada 1 / 2 / 3 |
| 10005213 | 400 | Número o booleano enviado como texto; mensagem señala la ruta | Envíe los números como número JSON y los booleanos como true / false |
| 10005214 | 400 | CFOP fuera del grupo: ISSQN solo con 5933, ICMS nunca con 5933 | Ajuste el CFOP al grupo |
| 10005216 | 400 | tipo distinto del actual en la actualización | El tipo no cambia; cree otra clase |
| 10005217 | 400 | Clase NFCe con un campo que la emisión de NFC-e no tiene; mensagem señala la ruta | Quite el campo, o cree una clase NFe |
| 10005218 | 400 | Grupo que el tipo no admite: issqn en NFe, ipi en NFCe | Quite el grupo |
| 10005219 | 400 | Clase NFCe con escenario fuera de SaidaDentroEstado / Padrao | Ajuste el escenario |
| 10004047 | 400 | Fila de ICMS de no contribuyente o persona física con código solo de contribuyente (10, 30, 70, 101, 201, 202, 203) o percentualCreditoSimples | Use 102 / 500 u otro código, o quite la dimensión |
| 10005008 | 400 | Fila de PIS / COFINS 01 con aliquota distinta de la alícuota legal del régimen de PIS/COFINS configurado en la empresa | Use la alícuota legal u omítala; vea «Régimen tributario» en Empresas |
| 10004046 | 400 | Có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.
| codigo | HTTP | Escenario | Acción |
|---|---|---|---|
| 10004000 / 10004001 | 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 |
| 10004051 | 400 | Có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 estado | Envíe el código IBGE o verifique cep / uf |
| 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 |
| 10005007 | 400 | Empresa CRT 3 sin alícuota de PIS / COFINS en el CST 01 y sin régimen de PIS/COFINS configurado: la plataforma no puede completarla | Envíe aliquota o configure el régimen en la consola, en «Datos tributarios»; vea Empresas |
| 10005008 | 400 | Empresa CRT 3 con alícuota de PIS / COFINS en el CST 01 distinta de la legal de su régimen de PIS/COFINS | Use la alícuota legal u omítala; vea Empresas |
| 10005202 | 400 | La clase de impuesto referenciada en la línea no existe, fue eliminada o es de otra empresa | Verifique classeImposto y empresaId, vea Clases de impuesto |
| 10005215 | 400 | Clase de otro tipo: la NF-e solo referencia clases NFe y la NFC-e solo clases NFCe | Referencie una clase del tipo correcto |
| 10005220 | 400 | La 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 |
| 10001002 | 400 | Línea con classeImposto que envía icms o issqn sin cfop | Envíe cfop en esa línea |
| 10005209 | 400 | La 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 contribuyente | Agregue 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.
| codigo | HTTP | Escenario | Acción |
|---|---|---|---|
| 10022006 | 404 | nfceId no existe | Revise el id y el empresaId |
| 10003000 | 404 | empresaId no existe | Revise el empresaId |
| 10022001 | 400 | NFC-e no habilitada en el ambiente actual de la empresa | Envíe ese ambiente en emissaoNFeConsumidor en el registro o la actualización |
| 10022002 | 400 | La empresa no puede emitir (no aprobada o certificado no disponible) | Espere la aprobación o envíe el certificado |
| 10022003 | 400 | ambienteEmissao distinto del ambiente actual de la empresa | Envíe en el ambiente de la empresa |
| 10022004 | 400 | Infringe una regla de la NFC-e; mensagem indica cuál | Corrija, o emita una NF-e |
| 10022007 | 400 | Plazo 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 |
| 10022008 | 400 | El estado no lo permite (no autorizada, cancelación en curso) | Consulte para confirmar el estado |
| 10022009 | 400 | El estado exige QR Code v2 y la empresa no tiene CSC utilizable | El QR Code v2 lo activa la plataforma y el CSC solo tiene efecto en producción; contacte a la plataforma |
| 10022024 | 400 | Có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 estado | Envíe el código IBGE o verifique cep / uf |
| 10001001 | 400 | Falló la validación de campos | Corrija según mensagem |
| 10005000 | 400 | El motor tributario rechazó la solicitud | Corrija según mensagem |
| 10005007 | 400 | Empresa CRT 3 sin alícuota de PIS / COFINS en el CST 01 y sin régimen de PIS/COFINS configurado: la plataforma no puede completarla | Envíe aliquota o configure el régimen en la consola, en «Datos tributarios»; vea Empresas |
| 10005008 | 400 | Empresa CRT 3 con alícuota de PIS / COFINS en el CST 01 distinta de la legal de su régimen de PIS/COFINS | Use la alícuota legal u omítala; vea Empresas |
| 10005202 | 400 | La clase de impuesto referenciada en la línea no existe, fue eliminada o es de otra empresa | Verifique classeImposto y empresaId, vea Clases de impuesto |
| 10005215 | 400 | Clase de otro tipo: la NF-e solo referencia clases NFe y la NFC-e solo clases NFCe | Referencie una clase del tipo correcto |
| 10005220 | 400 | La 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 |
| 10001002 | 400 | Línea con classeImposto que envía icms o issqn sin cfop | Envíe cfop en esa línea |
| 10005209 | 400 | La 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 contribuyente | Agregue una fila a la clase, o envíe el grupo en la solicitud; vea el orden de elección en Clases de impuesto |
| 10005205 | 400 | La fila elegida de la clase tiene un grupo o campo que la NFC-e no acepta; mensagem señala el campo | Cree 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.
| codigo | HTTP | Escenario | Acción |
|---|---|---|---|
| 10029100 | 404 | Empresa inexistente o de otro integrador | Revise el empresaId |
| 10029202 | 404 | Dispositivo inexistente o de otra empresa | Revise el dispositivoId |
| 10029101 | 200 | La 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 motivo | Una 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 |
| 10029104 | 200 | Emisión offline de la empresa desactivada por la plataforma | Contacte a la plataforma |
| 10029201 | 200 | La empresa ya tiene 20 códigos de emparejamiento pendientes | Úselos o espere a que venzan |
| 10029219 | 200 | ambiente distinto del ambiente actual de la empresa | Genere el código en el ambiente actual de la empresa |
| 10029221 | 200 | serie entre 890 y 999; la NFC-e de emisor CNPJ solo usa las series 0 a 889 | Use una serie de 0 a 889 |
| 10029222 | 200 | serie es la serie NFC-e del perfil de la empresa en alguno de los ambientes | Elija otra serie |
| 10029223 | 200 | serie ya la tiene otro dispositivo activo o un código pendiente de la empresa; message dice cuál | Elija otra serie |
| 10029224 | 200 | numeroInicial no es mayor que el mayor número conocido en la serie; message trae ese número | Envíe un número inicial mayor, u omítalo para continuar después de ese número |
| 10029225 | 200 | serie pertenece a un dispositivo desactivado o revocado que aún tiene notas offline por transmitir | Genere el código cuando el dispositivo anterior termine de transmitir |
| 10029001 | 200 | Valor de parámetro fuera de rango; message indica el campo | Corrija según los valores permitidos |
| 10001001 | 400 | Validación de campos de la solicitud | Corrija 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.
| codigo | Escenario | Acción |
|---|---|---|
| 10029203 / 10029204 | Dispositivo desactivado / revocado por la plataforma | Genere un nuevo código de emparejamiento |
| 10029205 | Código de emparejamiento inválido | Verifique que se copió completo; si hace falta, genere otro |
| 10029206 / 10029207 / 10029208 | Código de emparejamiento vencido / ya utilizado / anulado | Genere un nuevo código de emparejamiento |
| 10029209 | El código no permite esta forma (por ejemplo, código Assistente usado en el SDK) | Genere otro según la forma de integración |
| 10029210 | Emparejamiento por SDK sin nombre del software de caja | Informe el nombre del software de caja al iniciar |
| 10029501 | Software de caja bloqueado por la plataforma | Contacte a la plataforma |
| 10029211 | Versión del PDV bloqueada o por debajo de la mínima | Actualice el PDV |
| 10029212 | Versión del núcleo obsoleta | Actualice el Asistente Fiscal o el SDK |
| 10029213 | El CNPJ del certificado no coincide con el de la empresa | Use el certificado A1 de la empresa |
| 10029214 | Certificado vencido | Use un certificado válido |
| 10029219 | Ambiente 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 10029225 | La 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ódigo | Genere un código nuevo con otra serie u otro número inicial |
| 10029307 | Ambiente 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 rechazan | Genere un código en el ambiente actual, empareje un dispositivo nuevo y desactive el anterior |
| 10029424 | Nú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 sigue | La base local y los registros de la plataforma no coinciden; exporte los registros y contacte a la plataforma |
| 10029426 | En la emisión en línea del dispositivo, el mismo id ya tiene una nota no rechazada en la plataforma | Verifique 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.
| codigo | Constante | Escenario | Acción |
|---|---|---|---|
| 10029780 | ENGINE_TAX_CLASS_REQUIRES_ONLINE | Un í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 400 | Reenvíe con el mismo id cuando vuelva la red; sin red, envíe impostos en los ítems, vea Clases de impuesto y conexión |
| 10029801 | ENGINE_NOT_ACTIVATED | La empresa no está emparejada en este equipo, o el equipo aún no emparejó ninguna empresa | Guíe el emparejamiento; con varias empresas revise empresaId |
| 10029802 | ENGINE_EMPRESA_REQUIRED | Hay varias empresas emparejadas y no se indicó empresaId | Envíe empresaId |
| 10029803 | ENGINE_LICENSE_MISSING | No hay licencia para emisión offline | Sincronice en línea una vez (SincronizarAgora) |
| 10029804 | ENGINE_LICENSE_EXPIRED | Licencia vencida; la emisión offline se rechaza, la emisión en línea sigue normal | Restablezca la red; se renueva sola |
| 10029805 | ENGINE_LICENSE_SIGNATURE_INVALID | Firma de la licencia inválida | Atención manual: contacte a la plataforma, la base local puede haber sido alterada |
| 10029806 | ENGINE_LICENSE_NOT_FOR_DEVICE | La licencia no pertenece a este dispositivo | Atención manual: empareje de nuevo |
| 10029807 | ENGINE_OFFLINE_WINDOW_CLOSED | Pasó el plazo de emisión offline | Emita en línea cuando vuelva la red |
| 10029808 | ENGINE_LICENSE_QUOTA_EXHAUSTED | La serie del dispositivo llegó al número 999999999 | Desactive 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 |
| 10029809 | ENGINE_CLOCK_ROLLBACK | El reloj del sistema retrocedió | Atención manual: corrija la hora del sistema |
| 10029810 | ENGINE_TRANSMISSION_DEADLINE_REACHED | La nota pendiente más antigua superó el plazo de transmisión | Atención manual: restablezca la red cuanto antes para transmitir |
| 10029811 | ENGINE_OFFLINE_NOT_ALLOWED | La 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 nueva | Solo 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 |
| 10029812 | ENGINE_OFFLINE_FUEL_NOT_SUPPORTED | Las notas con combustible no se emiten offline | Emita cuando vuelva la red |
| 10029813 | ENGINE_CERTIFICATE_UNAVAILABLE | Certificado no encontrado, sin clave privada o con CNPJ distinto | Atención manual: revise el almacén de certificados; si hace falta, TrocarCertificado |
| 10029814 | ENGINE_CERTIFICATE_EXPIRED | Certificado vencido | Atención manual: renueve y llame TrocarCertificado |
| 10029815 | ENGINE_SNAPSHOT_MISSING | Faltan la configuración local o los datos tributarios, o no pasaron la verificación | Sincronice en línea; si persiste, contacte a la plataforma |
| 10029816 | ENGINE_DEVICE_DEACTIVATED | Dispositivo desactivado | Atención manual: contacte al integrador; las notas offline ya emitidas se siguen transmitiendo |
| 10029817 | ENGINE_REQUEST_INVALID | Solicitud inválida; Detalhes lista los motivos campo por campo | Corrija la solicitud; puede validarla antes con Previsualizar |
| 10029818 | ENGINE_DUPLICATE_ID_DIFFERENT_CONTENT | El mismo id ya se usó con contenido distinto | Venta nueva con id nuevo; para reintentar, reenvíe la solicitud original y recupere la nota |
| 10029819 | ENGINE_NOTE_NOT_FOUND | La nota no existe en este equipo | Revise id y empresaId |
| 10029820 | ENGINE_NOTE_NOT_CORRECTABLE | El estado actual no permite corregir | Solo Rejeitada admite Substituir |
| 10029821 | ENGINE_CORRECTION_CHANGES_TOTALS | La corrección cambió valores o impuestos | Cambie solo lo que no afecta valores |
| 10029822 | ENGINE_CANCEL_NOT_ALLOWED | El 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 |
| 10029823 | ENGINE_SERIE_EXHAUSTED | Numeración de la serie del dispositivo agotada | Desactive 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 |
| 10029824 | ENGINE_PLATFORM_UNREACHABLE | Una operación que requiere conexión (emparejamiento) no llega a la plataforma | Revise la red y reintente |
| 10029825 | ENGINE_ACTIVATION_CODE_INVALID | Formato, firma o vigencia del código de emparejamiento incorrectos | Atención manual: genere un código nuevo |
| 10029826 | ENGINE_ACTIVATION_HOST_UNTRUSTED | El código de emparejamiento apunta a una dirección de plataforma no confiable | Atención manual: confirme el origen del código y el ambiente del instalador (pruebas / producción) |
| 10029827 | ENGINE_KEY_PROTECTION_FAILED | El directorio de datos viene de otra computadora o de otro usuario de Windows | Atención manual: ejecute en la computadora y el usuario originales, o empareje de nuevo |
| 10029828 | ENGINE_DATA_DIR_LOCKED | El 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ó Encerrar | Cierre la otra instancia; antes de restaurar una copia de seguridad, llame Encerrar |
| 10029829 | ENGINE_LOCAL_STORE_CORRUPTED | Base local inconsistente | Atención manual: no borre el directorio de datos, contacte a la plataforma |
| 10029830 | ENGINE_PROTOCOL_VERSION_UNSUPPORTED | Versiones de SDK y runtime incompatibles | Actualice el SDK y el runtime juntos |
| 10029831 | ENGINE_RUNTIME_START_FAILED | Falló el inicio del runtime | Revise que el directorio del runtime esté completo y que el antivirus no lo bloquee |
| 10029832 | ENGINE_RUNTIME_CRASHED | El runtime terminó inesperadamente | Se puede reintentar; con reinicio automático el SDK se recupera solo, reenvíe la emisión con el mismo id |
| 10029833 | ENGINE_TIMEOUT | Tiempo de espera agotado | Reenvíe la emisión con el mismo id, o primero Consultar |
| 10029834 | ENGINE_SHUTTING_DOWN | Cerrando o ya cerrado | Llame de nuevo Iniciar |
| 10029835 | ENGINE_IN_PROCESS_UNSUPPORTED | El modo en proceso de Java exige Java 21 o superior | Use el modo subproceso |
| 10029836 | ENGINE_INTERNAL_ERROR | Error interno del núcleo; el mensaje trae un número de referencia | Contacte a la plataforma con el número de referencia y los logs |
| 10029837 | ENGINE_ALREADY_ACTIVATED | La empresa ya está emparejada en este directorio de datos | No hace falta emparejar de nuevo; para cambiar de equipo, desactive antes el dispositivo anterior |
| 10029838 | ENGINE_PLATFORM_RESPONSE_UNTRUSTED | Respuesta de la plataforma rechazada en la verificación; se conservaron los datos anteriores | Se reintenta sola; si persiste, revise si un proxy de red altera las respuestas |
| 10029839 | ENGINE_ACTIVATION_PERSIST_FAILED | La plataforma emparejó pero falló el guardado local | Empareje de nuevo con el mismo código de emparejamiento |
| 10029840 | ENGINE_CONFIG_INVALID | Configuración de inicio inválida | Corrija la configuración |
| 10029841 | ENGINE_AUTHORIZED_XML_UNAVAILABLE | XML autorizado no disponible: aún no autorizado, o no está en este equipo y no se pudo recuperar de la plataforma | Espere el evento de autorización y vuelva a pedirlo; si no se pudo recuperar, reintente más tarde |
| 10029842 | ENGINE_LOCAL_STORE_NEWER_VERSION | El 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 503 | Instale o actualice a una versión no inferior a la última usada; no borre el directorio de datos |
| 10029843 | ENGINE_CANCEL_XML_UNAVAILABLE | XML de cancelación no disponible: aún no cancelada, o no está en este equipo y no se pudo recuperar de la plataforma | Espere el evento de cancelación exitosa y vuelva a pedirlo; si no se pudo recuperar, reintente más tarde |
| 10029844 | ENGINE_EXPORT_FAILED | Falló 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 existe | Cambie de directorio o de nombre de archivo; revise el espacio en disco y los permisos |
| 10029845 | ENGINE_SUBSTITUTE_KEY_INVALID | La 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 empresa | Envíe la clave de 44 dígitos de la nota offline emitida por este dispositivo para la misma venta |
| 10029846 | ENGINE_BACKUP_INVALID | La 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 400 | Verifique la contraseña de la copia de seguridad; use otra copia de seguridad íntegra. La base original queda sin cambios |
| 10029874 | ENGINE_PARAMS_INVALID | Parámetro ausente o de tipo incorrecto; Detalhes.campo indica cuál | Corrija el parámetro, por ejemplo solicitud que no es objeto JSON, formato de la huella del certificado o de la fecha |
| 10029877 | ENGINE_RUNTIME_NOT_FOUND | Runtime no encontrado | Revise el instalador y el directorio del runtime |
| 10029878 | ENGINE_TOO_MANY_PENDING | Más de 64 llamadas en espera al mismo tiempo | Reduzca la concurrencia |
| 10029880 | ENGINE_PRINCIPAL_UNREACHABLE | Un 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 |
| 10029881 | ENGINE_PRINCIPAL_RESULT_UNKNOWN | La solicitud llegó al principal pero no volvió respuesta; resultado desconocido | Cuando vuelva el principal, consulte con el mismo id; reemitir con el mismo id y contenido no emite dos veces |
| 10029882 | ENGINE_TERMINAL_TOKEN_INVALID | Token del terminal secundario inválido o revocado | Emita otro token en el principal y actualice la configuración del secundario |
| 10029883 | ENGINE_PRINCIPAL_ADDRESS_INVALID | Dirección del principal mal formada o fuera de la red local privada | Corrija la dirección del principal en la configuración del secundario |
| 10029884 | ENGINE_MODE_METHOD_UNAVAILABLE | El modo actual no ofrece este método | Emparejamiento, cambio de certificado, copia de seguridad y exportación se hacen en el principal; la gestión de terminales solo en el principal |
| 10029885 | ENGINE_PRINCIPAL_REJECTED | El principal rechazó el origen de la solicitud, por ejemplo un secundario fuera de las redes permitidas | Revise las redes permitidas del principal y la red |
| 10029886 | ENGINE_PRINCIPAL_RATE_LIMITED | Demasiados fallos de autenticación; limitado por el principal | Revise el token y reintente tras 1 minuto |
| 10029887 | ENGINE_PRINCIPAL_LISTEN_FAILED | No se puede escuchar en el puerto de red local del principal | Cambie el puerto del principal o libere el puerto |
| 10029888 | ENGINE_TERMINAL_NOT_FOUND | El terminal a revocar no existe | Revise el identificador del terminal |
Asistente Fiscal
| codigo | HTTP | Escenario | Acción |
|---|---|---|---|
| 10029900 | 401 | Falta el token de caja | Envíe Authorization: Bearer tfl_… |
| 10029901 | 401 | Token de caja inválido o revocado | El gerente genera un token nuevo |
| 10029902 | 403 | El token no tiene acceso a esa empresa | Genere un token que incluya esa empresa |
| 10029903 | 403 | La dirección de origen no está en la red permitida del modo red local | Revise la configuración del modo red local |
| 10029904 | 400 | Dirección de callback inválida | Solo http / https; con el modo red local desactivado, solo la dirección de loopback |
| 10029905 | 401 | La acción del programa de escritorio exige sesión de gerente | Inicie sesión con el PIN de gerente |
| 10029906 | 401 | PIN de gerente incorrecto | Escríbalo de nuevo; 5 errores en total lo bloquean |
| 10029907 | 409 | Impresora no disponible | Revise la conexión de la impresora y la impresora elegida en Configuración |
| 10029908 | 409 | Asistente de instalación no terminado | Termine primero el asistente de instalación |
| 10029909 | 400 | Solicitud inválida | Corrija según mensagem |
| 10029910 | 404 | Recurso inexistente | Revise la ruta |
| 10029911 | 400 | Formato de PIN inválido; debe tener de 6 a 8 dígitos | Defínalo de nuevo con ese formato |
| 10029912 | 500 | Error interno del asistente | Exporte el paquete de diagnóstico y contacte a la plataforma |
| 10029913 | 403 | Cabecera Host de la solicitud del programa de escritorio no permitida; solo 127.0.0.1, localhost o [::1] con el puerto del asistente | Abra el programa de escritorio en http://127.0.0.1:puerto, sin proxy ni otro nombre de host |
| 10029914 | 429 | Demasiados errores de PIN; bloqueado | Espere al fin del bloqueo, vea las preguntas frecuentes del Asistente Fiscal |
| 10029916 | 409 | Puerto elegido ocupado o sin poder escuchar; configuración sin cambios | Elija otro puerto |
| 10029917 | 403 | La sesión de cajero no tiene acceso a esta empresa | Inicie sesión con el PIN de gerente para hacerlo |
| 10029918 | 429 | Asistente ocupado: ya hay 3 recuperaciones de XML en curso, o ya hay una exportación o una copia de seguridad en curso | Reintente más tarde, sin repetir llamadas seguidas |
| 10029919 | 400 | Configuración del proxy de salida inválida | En «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ó |
| 10029920 | 409 | Al 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 segundos | Espere a que terminen esas operaciones y vuelva a guardar o a restaurar; ni la configuración ni la base local se modificaron |
| 10029922 | 409 | El 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 seguridad | Libere espacio en ese disco y reintente |
| 10029923 | 403 | La 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 tiempo | Recargue la página; si persiste, vuelva a iniciar sesión con el PIN del gerente |
| 10029924 | 429 | Se abren sesiones de cajero con demasiada frecuencia: como máximo 20 por minuto desde el mismo origen | Espere 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.
| codigo | HTTP | Escenario | Acción |
|---|---|---|---|
| 10017002 / 10017003 | 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 |
| 10017050 | 400 | codigoIbge ausente y no se pudo completar por el CEP: cep ausente, fuera de la base o corresponde a más de un municipio | Envíe codigoIbge o verifique cep |
| 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 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.
| codigo | HTTP | Escenario | Acción |
|---|---|---|---|
| 10019002 / 10019003 | 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 |
| 10019012 / 10019010 | 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 |
| 10019014 | 400 | Empresa Marketplace / Carrier sin remetente | Añada el remitente |
| 10019015 | 400 | Falta remetente.endereco | Añada la dirección del remitente |
| 10019016 | 400 | Remitente brasileño sin cpfCnpj | Añada el documento del remitente |
| 10019004 | 400 | La empresa no puede emitir (no aprobada / certificado no listo) | Espere la aprobación / vincule el certificado |
| 10019017 | 400 | Destinatario brasileño sin cpfCnpj | Añada el documento del destinatario |
| 10019011 | 400 | Código IBGE del municipio no encontrado o inconsistente con uf | Compruebe cidade / uf |
| 10019049 | 400 | Có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 estado | Envíe el código IBGE o verifique cep / 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 |
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.
| codigo | HTTP | Escenario | Qué hacer |
|---|---|---|---|
| 10018001 | 400 | Validació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 / 10018003 | 404 | Documento no encontrado: el nfseId no pertenece a este emisor, o la clave de entrada no está entre sus facturas recibidas | Coteje nfseId / chaveAcesso con empresaId |
| 10018004 | 400 | Emisor no apto (desactivado / certificado inutilizable) | Revise el estado del emisor y el certificado |
| 10018005 | 400 | Emisor sin perfil de NFS-e; la mensagem señala el dato que falta | Envíe emissaoNFSe en el registro o actualice con id |
| 10018010 | 400 | El estándar de NFS-e del municipio aún no está admitido | Ese municipio todavía no puede emitir, contacte con la plataforma |
| 10018012 | 400 | Código de servicio fuera de la lista oficial LC 116 | Coteje codigoTributacaoNacional |
| 10018013 | 400 | Documento del receptor inválido | Coteje el CPF / CNPJ / NIF |
| 10018014 | 400 | Exportación de servicio sin país de destino | Informe servico.paisPrestacao |
| 10018015 | 400 | El documento sustituido no puede sustituirse | Revise el estado del documento sustituido |
| 10018020 | 400 | No 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 |
| 10018022 | 400 | Un emisor del Simples no puede enviar la alícuota de ISS directamente | Quite aliquota |
| 10018023 | 400 | La 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/cofins | Informe 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 / 10018031 | 400 | La misma solicitud ya se está procesando / ese pedido ya tiene factura o el mismo id trae contenido distinto | Reintente más tarde; use otro número de pedido o coteje el contenido |
| 10018040 | 400 | Ya hay un análisis de cancelación en curso | Espere el veredicto del municipio |
| 10018041 | 400 | El documento ya fue sustituido | No se permite ninguna otra operación |
| 10018042 | 400 | El 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 |
| 10018063 | 400 | El mensaje del DPS no cumple el XSD oficial; el detalle trae línea, columna, clave del error y nombre del elemento | Suele ser texto fuera de Latin-1, dirección incompleta, o un valor fuera de la tabla oficial |
| 10018064 | 400 | El mensaje de evento de la NFS-e no cumple el XSD oficial | Revise la longitud de motivo (15-255), el valor de codigoMotivo y el juego de caracteres |
| 10018065 | 400 | Los 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ón | Enví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 |
| 10018066 | 400 | Có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 estado | Enví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ódigo | HTTP | Caso | Acción |
|---|---|---|---|
| 10003000 | 404 | empresaId inexistente | Compruebe el empresaId |
| 10021001 | 404 | Plantilla de correo inexistente o de otro integrador | Compruebe el templateId |
| 10021002 | 400 | Plantilla desactivada, o su tipo de documento difiere de la factura | Use otra plantilla o actívela |
| 10021003 | 400 | La plantilla usa una variable fuera de la lista permitida | Corrija según la enumeración de variables |
| 10021004 | 400 | HTML de la plantilla con contenido prohibido o cuerpo de más de 64 KB | Corrija en los puntos que indica el mensaje |
| 10021005 | 400 | tipoDocumento no soportado en la lista de plantillas | Envíe solo NFe / NFSe / CTe / DCe |
| 10021010 | 404 | Factura inexistente o de otra empresa | Compruebe documentoId, tipoDocumento y empresaId |
| 10021011 | 400 | Factura aún no autorizada, o cancelada o sustituida | Envíe tras la autorización |
| 10021012 | 400 | Sin plantilla predeterminada para este tipo de documento | Envíe templateId o defina una plantilla predeterminada |
| 10021013 | 400 | Sin destinatario | Envíe destinatarios |
| 10021015 | 409 | El correo anterior de esta factura aún no terminó | Espere Enviado o Falha y reenvíe con un nuevo id |
| 10021020 | 404 | Correo inexistente o de otra empresa | Compruebe emailId y empresaId |
| 10001001 | 400 | Falló 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:
| 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 |
| 10015003 | Verificación de XML | La codificación no es UTF-8 | Convierta a UTF-8 antes de enviar |
| 10015005 | Verificación de XML | Retirado, 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 |
| 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 |
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.
| code | HTTP | Significado | Acción |
|---|---|---|---|
| 10015104 | 400 | Chave malformada (longitud / caracteres / dígito verificador) | Valide localmente primero: 44 dígitos; el último es un dígito verificador mod-11 |
| 10015300 | 404 | Su 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 |
| 10015301 | 409 | Verificación aún no terminada (PENDING_SEFAZ / VALIDATING) | Obtenga el PDF después de recibir invoice.verify.completed |
| 10015302 | 409 | El veredicto actual no genera PDF (solo lo generan VALIDATED y las facturas con status Cancelada) | No reintente |
| 10015303 | 409 | La plataforma no tiene el XML original de esta factura | Reenvíe el mismo XML sin cambios por la verificación de XML, sin forceRevalidate, y vuelva a obtenerlo |
| 10015304 | 503 | El XML original aún se está archivando | Reintente tras el Retry-After (5 segundos) |
| 10015305 | 503 | Generación ocupada o temporalmente no disponible | Reintente tras el Retry-After |
| 10001000 | 500 | Error interno de la plataforma | Reintente 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[].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 (status null) | Sí, reintentable | Fallo 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.
| 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: espere el
Retry-Aftery 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
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.
