Códigos de Error

Esta sección describe los códigos de error comunes que pueden ser devueltos por la API de Lummy Invoicing Service, junto con sus posibles causas y soluciones.

Errores HTTP Comunes

Código HTTP	Descripción General	Posibles Causas
400 Bad Request	La solicitud contiene datos inválidos o mal formados.	Parámetros faltantes, tipos de datos incorrectos, valores fuera de rango, datos no válidos según catálogos del SAT o reglas de negocio.
401 Unauthorized	La autenticación falló o no se proporcionaron credenciales.	x-api-key inválida o ausente en las cabeceras.
403 Forbidden	El usuario no tiene permisos para realizar la acción solicitada.	La clave API no tiene los permisos suficientes para el recurso o acción.
404 Not Found	El recurso solicitado no fue encontrado.	ID de sucursal, CSD o cliente no existentes.
409 Conflict	Conflicto con el estado actual del recurso.	La clave de idempotencia (x-idempotency) ya ha sido utilizada para una operación previa.
500 Internal Server Error	Un error inesperado ocurrió en el servidor.	Fallo en el procesamiento interno, problemas con servicios externos (PAC, SAT), o errores no controlados en la aplicación.

Errores Específicos de la Aplicación

Los siguientes errores pueden ser devueltos en la respuesta de la API, generalmente dentro de un 400 Bad Request o 500 Internal Server Error, y proporcionan más detalles sobre la causa del problema.

Código de Error (Interno)	Descripción	Posibles Causas
BRANCH_NOT_FOUND	No se encontró la sucursal especificada.	El sucursalId proporcionado en el request es inválido o no existe.
DISCOUNT_MISMATCH	El descuento especificado no coincide con los cálculos de la aplicación.	Discrepancia entre el descuento calculado y el proporcionado en los conceptos.
INVALID_CATALOG_VALUE	Un valor proporcionado no es válido según un catálogo del SAT.	Uso de un c_TipoDeComprobante, c_UsoCFDI, c_MetodoPago, etc., incorrecto o inexistente.
INVALID_PAYMENT_BALANCE	El saldo del pago es inválido.	En un Complemento de Pago, el impSaldoInsoluto o impPagado no cuadra.
INVALID_RFC_FORMAT	El formato del RFC es incorrecto.	RFC del emisor/receptor no cumple con la estructura esperada.
MISSING_CONDITIONAL_FIELD	Un campo condicional requerido está ausente.	Campo obligatorio para un escenario específico (ej. numLicencia para operador en Carta Porte) no se proporcionó.
MISSING_TAXES_ON_CONCEPT	Faltan impuestos en un concepto que los requiere.	Un concepto que debería llevar impuestos trasladados o retenidos no los especifica.
PAYMENT_AMOUNT_MISMATCH	El monto del pago no coincide con lo esperado.	Discrepancia entre el monto total del pago y la suma de sus componentes.
PAYMENT_METHOD_COMBINATION_ERROR	La combinación de forma y método de pago es inválida.	PUE debe ir con una formaPago que no sea 99, PPD solo con 99 (Por definir).
SAT_CATALOG_ERROR	Error al consultar o validar un catálogo del SAT.	Problemas internos con la sincronización o consulta de catálogos del SAT.
TAXES_NOT_ALLOWED_IN_GLOBAL_INVOICE_CONCEPT	Los impuestos no están permitidos en conceptos de facturas globales (Público General).	Se especificaron impuestos en un CFDI global (XAXX010101000) de forma incorrecta.
TOTALS_MISMATCH	Los totales del comprobante no coinciden con la suma de sus partes.	Suma de subtotales, descuentos e impuestos no es igual al total del comprobante.
UNEXPECTED_TAXES_ON_CONCEPT	Se especificaron impuestos donde no se esperaban.	Un concepto exento de impuestos o con un tipo de comprobante que no los permite tiene impuestos.
USE_CFDI_NOT_VALID_FOR_REGIMEN	El uso de CFDI no es válido para el régimen fiscal del receptor.	La combinación usoCFDI y regimenFiscalReceptor no es permitida por el SAT.
WITHHOLDING_NOT_APPLICABLE	Las retenciones no aplican para el concepto o escenario.	Se intentaron aplicar retenciones en un contexto donde no están permitidas.