Errores

El formato de error, la tabla de códigos y qué reintentar.

Todos los errores de la API comparten el mismo cuerpo:

{
  "code": "VALIDATION_ERROR",
  "message": "Error de validación",
  "errors": [ "cabecera.numero: obligatorio" ]
}

• code: código estable, pensado para tratarse por programa. Bifurca tu lógica sobre él: no sobre message, y no sobre el estado HTTP. El code identifica la condición concreta; el estado que la acompaña puede afinarse.
• message: descripción legible, en castellano.
• errors aparece en los errores de validación de cuerpo, con la lista de violaciones campo a campo, y en INVOICE_IDENTITY_CONFLICT, con los campos que difieren.
• campo: en los errores de parámetros de consulta, el parámetro concreto que los provocó (numero, fechaExpedicion, serie).

Un 500 no incluye el texto de la excepción interna: el cuerpo se limita a code y message, con una frase fija. Diagnostica por code; si necesitas más contexto, escríbenos indicando la hora de la petición.

Los rechazos que emite la pasarela antes de alcanzar la API no siguen ese formato. Un caso concreto: en los segundos posteriores a rotar una clave, la petición con la clave nueva recibe 403 con el cuerpo {"message": "Forbidden"} y sin code.

Códigos

Qué reintentar

El cliente de Python aplica esta política por ti, incluida la distinción entre un rechazo del servidor y una conexión caída. Lo que sigue es lo que hay que implementar si llamas a la API directamente.

• 429: espera y reintenta con retroceso exponencial. Si es por cuota mensual, el reintento inmediato no ayuda.
• 500 y 503: reintentables. La creación de facturas es idempotente por (emisor, serie, número, fecha): reintentar un alta cuya primera petición sí llegó devuelve 200 con el registro ya existente y yaExistente: true, no un duplicado.
• RECORD_PERSIST_ERROR: reintenta la misma petición. La factura está firmada pero no remitida, y el reintento la recupera y la envía sin volver a firmarla: no se duplica ni avanza la cadena de huellas. Es el único 500 cuyo reintento responde 200 con yaExistente: true.
• AWS_SERVICE_ERROR, ENQUEUE_ERROR, QR_GENERATION_ERROR y CHAIN_CONTENTION: reintentables. Los cuatro se devuelven antes de firmar y encadenar, o deshacen por completo lo escrito: no dejan a medias ningún registro ni consumen posición en la cadena de huellas.
• DATABASE_ERROR y AUTH_ERROR: reintentables.
• XML_PERSIST_ERROR: depende del message. Si dice que no se ha enviado nada, reintenta. Si es el de crear, no: la factura está firmada y encadenada, y hace falta intervención de soporte.
• INVOICE_IDENTITY_CONFLICT: no reintentes nunca. Con ese número ya consta otra factura. Una factura distinta necesita otro número; para cambiar una ya registrada, usa la subsanación o una rectificativa. Un reenvío idéntico sí responde 200 con el registro original.
• Resto de 4xx: el reintento sin corregir la petición obtiene la misma respuesta. Corrige y reenvía.

Cuentas multi-TPV

Los emisores con Alta capacidad contratada, donde cada dispositivo lleva su propia cadena de encadenado, tienen códigos propios. Las cuentas estándar no los reciben.

En los endpoints de emisión, y solo con el modo ya activo:

En los endpoints de gestión de dispositivos: 409 SHARDING_NOT_ENABLED, 409 MACHINE_ALREADY_REGISTERED, 404 MACHINE_NOT_FOUND, 409 CLIENT_NOT_IN_LIVE, 404 SERIE_NOT_RESERVED, 409 RESERVATION_LOCKED, 409 NOT_IN_PREPARATION y 503 ENVIRONMENT_NOT_AVAILABLE.

Si tu volumen lo requiere, habla con el equipo.