Errores específicos
Lista de los mensajes de error más comunes que devuelve la API, con su causa raíz y la acción recomendada.
| Mensaje | Causa | Solución |
|---|---|---|
"Producto X no encontrado." | idProducto no existe en el tenant. | Crear el producto en el POS, o corregir el ID. |
"Cliente X no encontrado." | idCliente no existe en el tenant. | Crear el cliente en el POS. |
"Factura electrónica requiere cliente." | Falta cliente en una FE, NC o ND. | Agregar el cliente al request. |
"Debe incluir al menos una línea." | El array lineas está vacío. | Agregar al menos una línea. |
"Línea N: la exoneración X no existe o no pertenece al cliente Y." | idExoneracion inválido o de otro cliente. | Consultar GET /clientes/{identificacion} y usar un idExoneracion del arreglo exoneraciones de ese cliente. |
"Línea N: la exoneración X está inactiva." | La exoneración fue desactivada en el POS. | Verificar estado/vigente en GET /clientes/{identificacion} antes de usar el id. |
"Línea N: la exoneración X venció el DD/MM/AAAA." | fechaExpiracion de la exoneración ya pasó. | Igual que el caso anterior — revisar vigente primero. |
"Línea N: se indicó 'idExoneracion' X pero el documento no tiene cliente." | Se envió idExoneracion en un Tiquete Electrónico sin cliente. | Enviar cliente.idCliente o cliente.identificacion, o quitar idExoneracion de la línea. |
"webhookUrl debe ser HTTPS." | El admin configuró un webhook con http://. | Usar URL https://. |
"Tipo no válido." | Valor de tipo no reconocido. | Usar un valor del enum TipoComprobanteApi. |
"Idempotency-Key reutilizada con body distinto." | Misma Idempotency-Key con un body diferente. | Generar una nueva key para el nuevo request. |
"Rate limit excedido." | Más de 120 req/min en una sola API key. | Aplicar backoff exponencial. |
"La API key no tiene el scope…" | La API key no tiene el scope requerido para esa operación. | Solicitar al admin el scope que nombra el propio mensaje. |