Saltar al contenido principal

Manejo de errores

Un rechazo de la SUNAT no es un error​

Esta es la regla más importante: si la SUNAT rechaza un comprobante o responde con un error propio (fault), xhandler no lanza una excepción ni devuelve un error. La respuesta llega como un valor más, igual que una aceptación, con su estado, código y descripción. Revisa Envío y respuestas de la SUNAT.

Solo obtienes un error cuando xhandler no pudo hacer su trabajo:

  • El documento tiene datos inválidos, por ejemplo un código de catálogo que no existe.
  • El certificado o su contraseña no son válidos.
  • El archivo no es un comprobante de la SUNAT, o falta la URL del servicio.
  • No se pudo conectar con la SUNAT, o su respuesta no se puede leer.

Tipos de error​

Java, Python y Go comparten el mismo modelo, porque los errores vienen del mismo núcleo: una excepción o error de xhandler con un tipo (kind).

TipoJava (ErrorKind)Python (ErrorKind)GoCuándo ocurre
ValidaciónVALIDATIONVALIDATIONKindValidationValores inválidos: un código de catálogo desconocido, una guía sin fecha de traslado.
Entrada inválidaINVALID_INPUTINVALID_INPUTKindInvalidInputFaltan campos o tienen tipos incorrectos; un XML que no es un comprobante; una guía sin URL de guías; un XML ya firmado al firmar; consultar el ticket de un documento que no usa tickets.
Llave inválidaINVALID_KEYINVALID_KEYKindInvalidKeyContraseña del certificado incorrecta, llave o certificado ilegibles, o un certificado que no corresponde a la llave.
Generación del XMLRENDERRENDERKindRenderNo se pudo generar el XML.
Respuesta ilegibleRESPONSERESPONSEKindResponseLa SUNAT respondió algo que no se puede leer, por ejemplo una página HTML de error.
Límite de peticionesRATE_LIMITEDRATE_LIMITEDKindRateLimitedEl proxy de la SUNAT siguió rechazando la petición después de los reintentos automáticos.
Petición inválidaINVALID_REQUESTINVALID_REQUESTKindInvalidRequestUso interno: la petición no llegó a ninguna operación del núcleo.

El mensaje de estos errores tiene la forma xhandler <tipo>: <mensaje>, por ejemplo xhandler validation: ....

Rust no tiene un único tipo de error: cada paso devuelve el suyo. Lo ves en la pestaña de Rust.

Manejar los errores​

import io.github.project.openubl.xhandler.core.ErrorKind;
import io.github.project.openubl.xhandler.core.XhandlerException;
import io.github.project.openubl.xsender.models.Status;
import io.github.project.openubl.xsender.models.SunatResponse;

import java.io.UncheckedIOException;

try {
String xml = new XBuilder().build(invoice);
byte[] signed = new XSigner().sign(xml.getBytes(StandardCharsets.UTF_8), key);
SunatResponse response = sender.sendFile(signed);

// Los rechazos de la SUNAT NO son excepciones
if (response.getStatus() == Status.RECHAZADO || response.getStatus() == Status.EXCEPCION) {
System.out.println(response.getMetadata().getResponseCode() + ": " + response.getMetadata().getDescription());
}
} catch (XhandlerException e) {
ErrorKind kind = e.getKind(); // null si el núcleo falló internamente
if (kind == null) {
throw e;
}
switch (kind) {
case VALIDATION -> System.out.println("Documento inválido: " + e.getMessage());
case INVALID_KEY -> System.out.println("Certificado o contraseña inválidos: " + e.getMessage());
case RESPONSE, RATE_LIMITED -> System.out.println("Problema con la SUNAT, reintenta más tarde: " + e.getMessage());
default -> System.out.println(e.getMessage());
}
} catch (UncheckedIOException e) {
// No se pudo conectar con la SUNAT (ya se reintentó una vez)
System.out.println("Sin conexión con la SUNAT: " + e.getMessage());
}
  • XhandlerException es una RuntimeException (unchecked). getKind() devuelve el ErrorKind, o null si el núcleo no pudo responder.
  • Los errores de red llegan como java.io.UncheckedIOException. También se usa si sendFile(Path) no puede leer el archivo, o si el hilo fue interrumpido.
  • Una URL inválida lanza IllegalArgumentException.
  • SigningKey.fromKeyStore lanza GeneralSecurityException (checked).

Qué hacer con cada error​

  • Validación, entrada inválida, generación del XML: corrige los datos del documento. Reintentar no sirve.
  • Llave inválida: revisa el certificado y su contraseña. Revisa Firma digital.
  • Respuesta ilegible, límite de peticiones o red: suelen ser problemas temporales de la SUNAT. Reintenta más tarde; xhandler ya reintentó lo razonable antes de devolverte el error.
  • Rechazo o error de la SUNAT (en la respuesta, no como error): revisa el código y la descripción. Un estado EXCEPCION (códigos 99 a 1999) permite corregir y reenviar; un RECHAZADO (2000 a 3999) es definitivo para ese comprobante.