Errores

Esta guía describe los tipos de errores que pueden presentarse al utilizar la API. En la mayoría de los casos se deben a problemas de implementación.

Antes de contactar a soporte, considere que el 99% de los casos reportados corresponden a errores de integración. Verifique exhaustivamente su implementación antes de solicitar asistencia.

Tipos de errores

Los errores se clasifican en dos niveles principales:

1. Errores de nivel 1

Corresponden a fallas de validación de los modelos de solicitud dentro de la API. Proporcionan información detallada y varían según la propiedad y el tipo de validador aplicado.

Los mensajes están en inglés, dirigidos a desarrolladores.
No está prevista su traducción.
Facilitan identificar problemas específicos durante la integración.

2. Errores de nivel 2

Estos errores se generan únicamente después de superar todas las validaciones de Nivel 1. Corresponden a las revisiones específicas requeridas por el SAT para el cumplimiento de CFDI 4.0.

Los mensajes están en español, siguiendo la normativa establecida.
Detallan las razones específicas de error según las especificaciones del SAT.
Consulte la tabla de errores CFDI 4.0 para obtener una descripción completa.

Los errores de Nivel 1 constituyen la primera etapa de validación. Si alguna validación de Nivel 1 falla, la API cancela la solicitud y devuelve el código de estado HTTP 400 Bad Request con el detalle de los errores. En ese caso, no se ejecutan validaciones de Nivel 2.

Para más detalles, consulte la documentación del modelo de respuesta de FiscalAPI.

Códigos de estado

Categorías de códigos de estado devueltos por la API. Úselas para determinar si una solicitud fue exitosa.

Name
2xx
Description
Indica una respuesta exitosa.
Name
4xx
Description
Indica un error del cliente; corresponde a un problema en la solicitud.
Name
5xx
Description
Indica un error del servidor; son poco comunes.

Errores específicos

Consulte las tablas completas de errores de nivel 2 en las siguientes páginas:

Errores CFDI 4.0 Errores de facturación general (códigos CFDI40xxx)
Errores Nómina 1.2 Errores del complemento de Nómina (códigos NOMxx)
Errores Carta Porte 3.1 Errores del complemento de Carta Porte (códigos CPxxx)