Saltar al contenido
Verificada

Códigos de error

Cada código negativo y estado HTTP del catálogo de errores de CPI, qué significa y qué hacer.

Xuda mantiene un único catálogo de todos los errores con los que puede volver una llamada. Esta página es ese catálogo, organizado según dónde aparece el error. Consulta Errores para ver el enfoque específico de la API de los mismos códigos.

Errores de estado HTTP

Son los estados que ves en la capa de transporte, tanto si accedes directamente a una página como si haces una llamada cpi.

Códigos del contrato con el cliente

El propio cliente del dashboard reconoce estos códigos y arranca un flujo de interfaz concreto a partir de ellos, en lugar de mostrar un mensaje de error genérico. La facturación pasó de un saldo prepago a facturas pospago, así que las únicas barreras que quedan en una acción de pago son la falta de tarjeta y una factura vencida. -92 (saldo negativo) y -93 (recarga necesaria) ya no existen en la barrera de cuenta que antes los lanzaba; el cliente sigue teniendo un manejador de -93 por compatibilidad, solo que ya no hay nada que lo active.

El sobre de respuesta

Todo método, con éxito o con error, responde { code, data }. code >= 1 es éxito; code < 0 es un error. Algunos errores de la capa HTTP añaden una clave error de texto junto al code numérico ("rate_limited", "invalid_fields", "appeal_failed"), a veces con un array fields: [].

CPI asigna un code negativo a un estado HTTP con una sola regla: un código de -400 a -499 se convierte en ese estado exacto (-400 responde HTTP 400, -404 responde HTTP 404, -409 responde HTTP 409, -428 responde HTTP 428). Cualquier otro código negativo, -1, -500, -762, -999, todo lo que quede fuera de esa banda, también responde un HTTP 400 normal. Unos pocos endpoints distintos y más acotados (algunas rutas de pago de tienda y de formularios públicos, no el despacho general /cpi/<method>) asignan solo -404/-403/-400 y por defecto devuelven 422 en todo lo demás; esa asignación es local a esas rutas y no describe la regla general anterior, así que un -400 del despacho general es HTTP 400, no 422.

El mismo número se reutiliza en distintos métodos con significados diferentes, sobre todo -1 y -400. Lee siempre el mensaje de data y el método que llamaste; los significados de abajo son el caso habitual, no una garantía.

Códigos negativos de CPI

Los códigos en los que conviene ramificar la lógica, reunidos tras un barrido de cada cpi/*_module.

Aparte de esta tabla, cada módulo usa códigos negativos pequeños (aproximadamente de -2 a -25, -44/-45/-46, de -64 a -78, -99/-101/-106) para estados intermedios propios del módulo. Casi siempre van acompañados de un mensaje descriptivo en data, a menudo err.message. Cuando te encuentres con uno, lee el texto de data y el método de origen en lugar de fiarte solo del número.

Errores internos o no declarados

Unos pocos fallos nunca llegan al sobre { code, data }: una excepción no capturada, un rechazo de promesa no gestionado, un throw new Error(...) que aparece como un 401 o 500 simple (por ejemplo 'app is off', 'Account suspended', 'Account terminated'), o un fallo del bróker de mensajes. Se detectan por su forma u origen y no por un código fijo, y siempre conviene escalarlos en lugar de reintentar a ciegas.