Specific errors
List of the most common error messages returned by the API, with their root cause and the recommended action.
| Message | Cause | Solution |
|---|---|---|
"Producto X no encontrado." | idProducto does not exist in the tenant. | Create the product in the POS, or fix the ID. |
"Cliente X no encontrado." | idCliente does not exist in the tenant. | Create the customer in the POS. |
"Factura electrónica requiere cliente." | cliente is missing on an FE, NC, or ND. | Add cliente to the request. |
"Debe incluir al menos una línea." | The lineas array is empty. | Add at least one line. |
"Línea N: la exoneración X no existe o no pertenece al cliente Y." | Invalid idExoneracion, or it belongs to another customer. | Query GET /clientes/{identificacion} and use an idExoneracion from that customer’s exoneraciones array. |
"Línea N: la exoneración X está inactiva." | The exemption was deactivated in the POS. | Check estado/vigente in GET /clientes/{identificacion} before using the id. |
"Línea N: la exoneración X venció el DD/MM/AAAA." | The exemption’s fechaExpiracion has already passed. | Same as above — check vigente first. |
"Línea N: se indicó 'idExoneracion' X pero el documento no tiene cliente." | idExoneracion was sent on a Tiquete Electrónico with no cliente. | Send cliente.idCliente or cliente.identificacion, or remove idExoneracion from the line. |
"webhookUrl debe ser HTTPS." | The admin configured a webhook with http://. | Use a https:// URL. |
"Tipo no válido." | The tipo value is not recognized. | Use a value from the TipoComprobanteApi enum. |
"Idempotency-Key reutilizada con body distinto." | Same Idempotency-Key with a different body. | Generate a new key for the new request. |
"Rate limit excedido." | More than 120 req/min on a single API key. | Apply exponential backoff. |
"La API key no tiene el scope…" | The API key does not have the scope required for that operation. | Ask the admin for the scope named in the message itself. |