Errores

Esta guía describe cómo se clasifican los errores de la API, qué indica cada código de estado y cómo interpretar las respuestas de error más comunes.

Tipos de errores

Los errores se clasifican en dos niveles. Si falla alguna validación de nivel 1, la API detiene la solicitud y responde 400 (Bad Request) con el detalle de las fallas, sin ejecutar las validaciones de nivel 2.

1. Errores de nivel 1

Son las fallas de validación de la solicitud, que la API revisa antes de procesarla. Cada falla indica la propiedad que falló (propertyName) y un mensaje que depende de la regla aplicada. Usa la propiedad, y no el texto del mensaje, para identificar la falla en tu código (ver ValidationFailure).

Los mensajes están en español; por ejemplo, 'transpInternacId' no debe estar vacío. Algunos mensajes propios de reglas (ver Mensajes de validación del timbrado) y los errores de lectura del JSON, como un JSON mal formado o un valor de otro tipo, están en inglés.

2. Errores de nivel 2

Son las revisiones que el SAT exige para cumplir con el CFDI 4.0. Sus mensajes están en español y explican la causa según las especificaciones del SAT. Consulta la tabla de errores CFDI 4.0 para ver la lista completa.

Códigos de estado

La categoría del código de estado indica si la solicitud tuvo éxito. El cuerpo de la respuesta sigue el modelo de respuesta de FiscalAPI.

Recurso no encontrado

Cuando un endpoint busca un recurso por su id y el recurso no existe en tu cuenta, responde 404. El id puede ir en la ruta, como en Obtener factura por ID, o en el cuerpo, como invoiceId en Generar pdf por ID. Los endpoints con un mensaje propio para este caso lo indican en su sección (por ejemplo, certificados).

En los mensajes, <id> es el id enviado y <catalogName> es el nombre del catálogo en la ruta, que distingue mayúsculas y minúsculas: satpaymentforms no es SatPaymentForms.

El nombre del catálogo se revisa en todas las rutas que lo llevan: GET /api/v4/catalogs/<catalogName>, Obtener registro por ID, Buscar en un catálogo, GET /api/v4/catalogs/<catalogName>/load y Listar catálogo de los catálogos de descarga masiva. Los nombres válidos son los que devuelven Listar catálogos y Listar catálogos de descarga masiva.

Claves de catálogo del SAT

Cuando un campo lleva una clave que no está en su catálogo del SAT, el endpoint responde 400 con una falla de validación en ese campo. El mensaje, en español, trae el valor recibido y el nombre del catálogo, sin la lista de claves.

La regla aplica a las facturas (POST /api/v4/invoices) y a su cancelación, que rechaza el motivo sin llamar al PAC. También aplica a los productos, las personas (emisores y receptores) y los datos de empleado y empleador. Consulta las claves válidas con la API de catálogos.

Cada campo responde una sola falla: en los campos obligatorios con esta regla (por ejemplo, versionCode, typeCode, los impuestos o las claves de nómina), un valor vacío o ausente responde solo el mensaje de campo vacío. Los campos siguientes tienen un mensaje propio, distinto de la forma general:

Valores que no caben en la factura

Al timbrar (POST /api/v4/invoices, por valores o por referencias, con cualquier tipo de factura y complemento) y al calcular (POST /api/v4/invoices/calculate), Fiscalapi arma la factura que guardaría y revisa que cada valor quepa en ella. Un texto no puede ser más largo que su máximo, y un importe o una cantidad, redondeado a sus decimales, no puede tener más dígitos enteros que los admitidos. Por ejemplo, la cantidad del concepto y el monto del pago admiten 12: valores menores que 1000000000000.

Si un valor no cabe, el endpoint responde 400 con una falla de validación por cada valor, sin timbrar y sin consumir timbre. Al timbrar, la revisión ocurre antes de cobrar el timbre y de llamar al PAC; el cálculo nunca timbra ni consume timbre.

En esta falla, propertyName es la ruta del dato en la factura guardada, no la del campo del request:

Otras rutas posibles son, por ejemplo:

Las reglas propias de los campos del request (por ejemplo, el correo del receptor de hasta 256 caracteres o itemSku de hasta 100) responden antes, con la falla en el campo del request.

Decimales de importes, cantidades y tasas

Al timbrar (POST /api/v4/invoices, por valores o por referencias) y al calcular (POST /api/v4/invoices/calculate), los importes, cantidades y tasas que van tal cual al XML admiten como máximo los decimales que el SAT define para su atributo (XSD del CFDI 4.0 y de sus complementos). Un valor con más decimales responde 400 con una falla de validación por cada valor, antes de cobrar el timbre y de llamar al PAC:

Fiscalapi no redondea el valor: redondéalo en tu sistema al número de decimales que corresponda antes de enviarlo. Por ejemplo, a 6 decimales:

Solo cuentan los decimales significativos, no los ceros finales. Por ejemplo, se aceptan 0.16000000 en taxRate y un tipo de cambio de 1.0000000 con moneda MXN. Los límites, según el atributo del XML, son:

La regla aplica al campo aunque, en una factura concreta, su valor no llegue al XML (por ejemplo, totalInstallments y dailyAmount junto con totalOneTime). No aplica a los campos que Fiscalapi redondea al armar el XML (el importe de otros pagos de nómina, los impuestos locales y los importes de Comercio Exterior) ni a los de Carta Porte y Comercio Exterior, que validan sus decimales con su propio mensaje.

El campo daysPaid (días pagados de la nómina) acepta un entero o hasta 3 decimales. Fiscalapi lo escribe en el XML como lo pide el SAT: entero, o con exactamente 3 decimales.

Fiscalapi escribe algunos números con su propia escala, como la tasa o cuota y el tipo de cambio con MXN; por eso los ceros de más en esos campos no llegan al XML. Un importe que va tal cual al XML con ceros de más (por ejemplo, 200.0000000 en unitPrice) lo rechaza el PAC con CFDI40999: envía como máximo los decimales del atributo.

Mensajes de validación del timbrado

Al timbrar (POST /api/v4/invoices, por valores o por referencias) y al calcular (POST /api/v4/invoices/calculate), los mensajes de validación están en español y nombran el campo como en la API: en camelCase, igual que en el JSON. Los demás endpoints nombran el campo con el nombre de la propiedad separado en palabras.

El campo de la falla (propertyName) es la ruta del dato en el request, en PascalCase (por ejemplo, Items[0].ItemTaxes[0].TaxCode). Úsalo, y no el texto, para identificar la falla (ver ValidationFailure).

Estas reglas del timbrado tienen un mensaje propio. En los mensajes, <campo> es el nombre del campo como en la API; por ejemplo, 'date'. <régimen> y <uso> son las claves del receptor, y el tipo de persona (moral o física) es el que corresponde a la longitud de su RFC.

Una factura con más de 1,500 conceptos responde 400 sin falla de validación, tanto al timbrar como al calcular:

Están en inglés los mensajes de catálogo de Carta Porte y Comercio Exterior, los de los archivos de certificados y los del lector de JSON (JSON mal formado o un valor de otro tipo). Por ejemplo:

Elementos null en listas

Cada elemento de una lista de objetos del cuerpo debe ser un objeto. Un elemento null, como en "relatedInvoices": [null] o "productTaxes": [{ ... }, null], responde 400 con una falla de validación por cada elemento null:

Esta revisión corre antes que las demás validaciones y antes de llamar al PAC: la respuesta trae solo las fallas de los elementos null, sin timbrar ni consumir timbre. Si además el cuerpo no se puede leer (por ejemplo, un valor de otro tipo), responde solo la falla de lectura.

Al timbrar y al calcular, el mensaje nombra el campo como en la API, en camelCase. Los demás endpoints lo nombran con el nombre de la propiedad separado en palabras.

Un elemento null responde solo esta falla, en su posición, también en las listas que tienen su propia regla: taxCredentials (el par de certificados y la lista vacía), paidInvoices y paidInvoiceTaxes (la lista vacía) y las ubicaciones de Carta Porte (mínimo 2).

Las listas de textos (por ejemplo, validationTypes de las validaciones SAT) conservan su propia regla. El campo metadata es un diccionario y no una lista: acepta valores null.

Certificados y llaves privadas

Los endpoints que reciben una llave privada (archivo .key) con su contraseña la abren antes de usarla. Si la contraseña no abre la llave, responden 400 con una falla de validación en el campo de la contraseña. La misma falla sale si el archivo enviado como llave no es una llave privada: la lectura de la llave no distingue los dos casos. La revisión ocurre antes de llamar al PAC y sin consumir timbre.

La cancelación por valores (con taxCredentials) no abre la llave: la envía al PAC, que responde su propio error si la contraseña no corresponde.

Otros errores de certificados y llaves:

El 500 es un error del servidor y no de la solicitud: repetirla con otros datos no lo resuelve, así que escribe a soporte.

Errores del servidor

Un error del servidor (5xx) no se resuelve cambiando los datos de la solicitud. La respuesta trae traceIdentifier (ver ApiResponse): inclúyelo al escribir a soporte, porque identifica la petición en los registros de Fiscalapi. El campo message indica de qué lado está la causa:

Conservan su propio message el rechazo del PAC al timbrar o cancelar, el 425 (Too Early) de Descargar paquete por ID y el 429 (Too Many Requests) del límite de solicitudes. Los errores del servidor responden así:

Ejemplo (error inesperado):

{
  "data": null,
  "succeeded": false,
  "message": "Something went wrong on our end.",
  "details": "Ocurrió un error inesperado en el servidor. Escríbenos a soporte@fiscalapi.com con el traceIdentifier de esta respuesta.",
  "httpStatusCode": 500,
  "traceIdentifier": "5C1E0B7A92D44F3E8A6B1D07F3C29E41"
}

Resultado incierto del timbrado

Al timbrar, si el PAC no responde a tiempo o responde un error de su servidor sin un código de rechazo, el resultado es incierto: el CFDI pudo quedar timbrado. Fiscalapi responde el error inesperado (500) y conserva el timbre consumido y el folio de la factura para conciliarlos; no los devuelve.

No repitas la factura de inmediato, porque podrías timbrar dos veces la misma operación. Consulta tus facturas con Listar facturas y, si no aparece, escribe a soporte con el traceIdentifier de la respuesta. Un rechazo del PAC con su código sí es un rechazo: se reembolsa el timbre y la respuesta trae el mensaje del PAC.

Restricciones de los datos y concurrencia

Al escribir los datos, la base de datos de Fiscalapi también rechaza lo que la solicitud causó y que no detectó antes una validación del campo. Estas respuestas son errores del cliente y no traen falla de validación ni campo: el motivo va en details, en español.

Ante un 409, vuelve a consultar el registro y repite la solicitud. Las personas conservan su propio 409 (ver Actualizar emisor). Cualquier otra falla de la base de datos responde el error inesperado (500).

Errores específicos

Las tablas completas de errores de nivel 2 están en estas páginas: