Troubleshooting

”I get 401 Unauthorized”

1. Verify the header is X-Api-Key (not Authorization).
2. The full key, with no leading/trailing spaces.
3. It starts with lxs_live_.
4. It has not been revoked (check with the administrator).

”I get 403 Forbidden”

The key doesn’t have the scope. The error message names which one is missing. Ask the administrator to add it:

• facturas:read for GET on /facturas.
• facturas:write for POST /facturas with tipo FE or TE.
• notas:write for POST /facturas with tipo NC or ND.
• facturas:anular for DELETE /facturas/{clave}.
• facturas-compra:write for POST /facturas-compra.
• facturas-compra:read for GET /facturas-compra/{clave} and /pdf.

”I get 400 when issuing an NC or ND and the message doesn’t say what’s missing”

The first thing to check is the reference reason code. The system expects a 2-digit code from the catalog in referencias[0].codigo or in referencias[0].razon. A reference with only free text in both fields will not issue:

"referencias": [
  { "tipoDocumento": "01", "numero": "5062508…", "razon": "Cargo por interés moratorio" }
]

The 400 message lists the codes the tenant accepts. With the code present in either field, the issuance goes through:

"referencias": [
  { "tipoDocumento": "01", "numero": "5062508…", "codigo": "10", "razon": "Cargo por interés moratorio" }
]

The second thing is idUsuario: it must exist in the tenant. The examples in this documentation use 7, but each tenant has its own ids — the administrator provides the correct one along with the API key.

”I requested moneda: CRC and the document came out in USD”

This is not a request error. If the tenant is not enabled for multi-currency, the document is issued in its primary currency even if another one is requested, and the response returns the currency it was actually issued in. Ask the administrator to enable multi-currency on the tenant.

An NC or ND also has its own rule: it inherits the currency of the document it references, because Hacienda requires them to match. See multi-currency.

”The amount came out much lower than expected”

The line was likely issued without precioUnitario in a currency different from the tenant’s catalog. The list price is converted using the exchange rate, but it’s best to send an explicit precioUnitario when the integrator’s system already manages its own prices: it’s the most predictable way to integrate.

If the amount shows as zero when querying a document that was issued with a correct amount, check whether a credit note was issued against it: a full NC leaves the document credited down to zero.

”I get 400 with Producto X no encontrado”

The product doesn’t exist in the tenant’s catalog. Solutions:

1. Create the product in the POS.
2. Use another valid idProducto.
3. Verify you’re pointing to the correct tenant (the key’s prefijo).

”My document stays in procesando for hours”

Possible causes:

1. Hacienda overloaded (month-end close, filings).
2. Expired P12 certificate on the tenant.
3. Incorrect Hacienda credentials.

If more than 30 minutes pass, escalate to support.

”Hacienda rejects with code 9015”

This is a validation failure against the official catalogs. Check that the following fields are within the values Hacienda allows:

• condicionVenta.
• medioPago.
• tipoIdentificacion of the customer.

”My webhook isn’t arriving”

Check the webhooks section: verify that webhookUrl is configured, that the receiving endpoint responds 2xx promptly, and that it isn’t blocked by a firewall.

”I keep getting 429”

The 120/min limit is being exceeded. Solutions:

1. Implement rate limiting on the integrator’s side.
2. Distribute the load across multiple keys (if managing several tenants).
3. Request a limit increase from support.