Errores

Toda respuesta de error sigue RFC 9457 (Problem Details):

{
  "type": "/v1/errores/llave-invalida",
  "title": "No autenticado",
  "status": 401,
  "detail": "Falta la llave o no es valida. Confirma con GET /v1/llaves/actual.",
  "code": "FACTO-2001",
  "requestId": "b3e1..."
}

Las tres cosas que importan

code es estable. Programa contra él. El texto de detail puede mejorar entre versiones; el código no cambia nunca.

type resuelve. Es una URL al catálogo que sirve la propia API: GET /v1/errores lista todos los errores posibles (es público, sin llave) y GET /v1/errores/{slug} explica cada uno con qué hacer.

requestId es tu ticket. Viene en el cuerpo y en la cabecera x-request-id. Si algo raro pasa, repórtalo con ese identificador y del otro lado se encuentra la petición exacta en los logs.

Cuando el problema es campo a campo, errors[] lo detalla con la ruta completa:

{
  "code": "FACTO-HTTP-400",
  "errors": [
    { "field": "detalles.0.cantidad", "message": "debe ser un numero en texto" }
  ]
}

400 contra 422

• 400 — la petición no se entiende (tipos, formatos, largos del JSON). Se arregla mirando errors[].
• 422 — la petición se entiende, pero el SRI no la aceptaría (dígito verificador inválido, catálogo equivocado, importes que no cuadran). El code de la serie FACTO-1xxx nombra la regla exacta.

Las dos series

• FACTO-1xxx — reglas del dominio fiscal: certificado, numeración, esquema del SRI, estados del comprobante.
• FACTO-2xxx — transporte HTTP: autenticación, idempotencia, límites, saldo de la cuenta.

El catálogo completo, con quién arregla cada error y cómo, vive en la propia API: GET /v1/errores.

Los mensajes del SRI son otra cosa

Cuando el SRI devuelve o rechaza un comprobante, sus mensajes (código 43, 45, 70…) llegan textualmente en mensajes[] del comprobante, acompañados de una guia con qué hacer y quién puede arreglarlo:

{
  "estado": "NO_AUTORIZADO",
  "mensajes": [
    {
      "identificador": "58",
      "mensaje": "ERROR FIRMA INVALIDA",
      "informacionAdicional": "...",
      "guia": "El certificado no corresponde al RUC del comprobante..."
    }
  ]
}

Esos códigos son del catálogo del SRI, no de esta API. Ante un reclamo, la prueba es el texto original — por eso llega sin traducir.