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