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 solo en errores de validación de cuerpo: la lista de violaciones, campo a campo.
• campo: en los errores de parámetros de consulta, el parámetro concreto que los provocó (numero, fechaExpedicion, serie).

Un 500 nunca lleva 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. El caso que conviene conocer: 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 en crudo.

• 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, 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 sin reservas. 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.
• Resto de 4xx: no reintentes sin corregir la petición, porque el resultado será el mismo.

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 ven nunca.

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.