Codigos de error

Codigos de error

Esta referencia combina dos capas de error:

1. validaciones y rechazos del modulo ms-recargas
2. respuestas de negocio y transporte del SPR de Claro

Tabla resumen

Capa	Escenario	Respuesta	Estado final esperado
HTTP modulo	JWT invalido	401	rechazo inmediato
HTTP modulo	Falta permiso	403	rechazo inmediato
HTTP modulo	Action token invalido	401	rechazo inmediato
HTTP modulo	Limite diario o rate limit	429	rechazo inmediato
HTTP modulo	Service key invalida	401	rechazo inmediato
HTTP modulo	DTO invalido	400	rechazo inmediato
Webhook	source_xml_hash duplicado	409	rejected o conflicto
Webhook	product_code sin mapping	400 o 201 rechazado	rejected
Claro negocio	STATUS=ERROR o ID_CODIGO != 0	200 con error logico	failed
Claro transporte	SOAP Fault	502	unavailable
Claro transporte	timeout	504	unavailable
Claro red/config	IP no validada	fault 350	unavailable

---

Gates de validacion del proceso

#	Gate	Capa	Aplica a	Resultado al fallar
1	JWT invalido o expirado	AuthGuard	Manual	401
2	Falta create_recargas o view_recargas	PermissionsGuard	Manual	403
2.a	X-Action-Token ausente, invalido o ya usado	ActionTokenGuard	Manual	401
2.b	Limite diario alcanzado	DailyRechargeLimitGuard	Manual	429
2.c	Rate limit recharge	ThrottlerGuard	Manual	429
3	Service key invalida	ServiceKeyGuard	Automatico	401
4	Telefono invalido	DTO o webhook	Ambos	400
5	Producto sin mapping	WebhookService	Automatico	400 o rejected
6	Factura duplicada por hash	DB / servicio	Automatico	409
7	external_transaction_id duplicado	DB / Claro	Ambos	failed o rechazo
8	SOAP Fault o timeout	ClaroClientService	Ambos	502 o 504
9	STATUS=ERROR o result != 0	RecargasService	Ambos	failed
10	Excepcion inesperada	filtro global	Ambos	500

Errores del modulo ms-recargas

JWT invalido o expirado

Se devuelve 401 Unauthorized. Aplica a endpoints del dashboard.

Permiso insuficiente

Se devuelve 403 Forbidden cuando el usuario autenticado no tiene create_recargas o view_recargas.

Service key invalida

Se devuelve 401 Unauthorized en el webhook. La factura no debe procesarse.

DTO invalido

Se devuelve 400 Bad Request cuando faltan campos o el formato de datos no cumple las reglas.

Factura duplicada

Si source_xml_hash ya existe, el webhook responde 409 Conflict para mantener idempotencia.

Producto sin mapping

Si n8n envia un SKU como RECCLARO99 y no existe una fila de traduccion hacia Claro, la transaccion se rechaza antes de llamar al SPR.

Respuesta tipica:

{
  "success": false,
  "status": "rejected",
  "error": "Codigo de producto RECCLARO99 no tiene mapeo a Claro"
}

---

Errores del SPR de Claro

IP no validada en la configuracion del SPR

La IP desde la que se invoca el servicio no esta registrada. El gateway responde con un SOAP Fault en lugar del formato <umsprot>:

<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:ns0="http://claro/">
  <env:Body>
    <env:Fault>
      <faultcode>350</faultcode>
      <faultstring>El id_requerimiento es nulo debido a que el xml
      recibido en el body del request no corresponde a ningun formato
      configurado para la ip del llamante: 10.35.2.31</faultstring>
      <data name=" CODIGO ERROR"">1</data>
    </env:Fault>
  </env:Body>
</env:Envelope>

Impacto esperado: ms-recargas debe marcar la transaccion como unavailable, devolver 502 y registrar alerta claro.ip_rejected.

Usuario incorrecto o inactivo

El USERID enviado es invalido o esta desactivado:

<umsprot version="1">
  <exec_rsp result="OK" diagnostic="Conexion Exitosa">
    <data name="MENSAJE">El usuario ingresado es incorrecto o se
    encuentra inactivo.R.12</data>
    <data name="ID_CODIGO">1</data>
    <data name="STATUS">ERROR</data>
  </exec_rsp>
</umsprot>

Clave incorrecta

El PASSWORD enviado no corresponde al USERID:

<umsprot version="1">
  <exec_rsp result="OK" diagnostic="Conexion Exitosa">
    <data name="MENSAJE">La clave ingresada es incorrecta. R.11</data>
    <data name="ID_CODIGO">1</data>
    <data name="STATUS">ERROR</data>
  </exec_rsp>
</umsprot>

Parametros obligatorios faltantes

Un campo requerido esta vacio o ausente:

<umsprot version="1">
  <exec_rsp result="OK" diagnostic="Conexion Exitosa">
    <data name="SYSTEMMESSAGE">El siguiente parametro es requerido
    para la transaccion solicitada: EXTERNALTRANSACTIONID</data>
    <data name="ID_CODIGO"/>
    <data name="STATUS">ERROR</data>
  </exec_rsp>
</umsprot>

Duplicidad de COMPANYID + EXTERNALTRANSACTIONID

Claro rechaza la recarga cuando el identificador ya fue usado:

<umsprot version="1">
  <exec_rsp result="OK" diagnostic="Successful balance request">
    <data name="SYSTEMMESSAGE">Imposible realizar la recarga.
    Intente nuevamente.-</data>
    <data name="ID_CODIGO">R.AV.7</data>
    <data name="STATUS">ERROR</data>
  </exec_rsp>
</umsprot>

Impacto esperado: la transaccion no debe marcarse como exitosa. Si el identificador ya fue consumido, se debe analizar antes de reintentar para no duplicar recargas.

---

Estados terminales recomendados

Estado	Cuando aplica
success	Claro confirma STATUS=SUCCESS e ID_CODIGO=0
failed	Claro responde error de negocio
unavailable	SOAP Fault, timeout, ECONNREFUSED, VPN o IP no autorizada
rejected	El webhook rechaza la factura antes de llamar a Claro
ignored	n8n descarta el correo y solo se bitacora
error	Solo para registros legacy

---

Errores de consulta de recarga

Transaccion no encontrada

<umsprot version="1">
  <exec_rsp result="OK" diagnostic="Conexion Exitosa">
    <data name="SYSTEMMESSAGE">Transaccion no encontrada</data>
    <data name="ID_CODIGO">1</data>
    <data name="STATUS">ERROR</data>
  </exec_rsp>
</umsprot>

Producto de recarga incorrecto para consultar

<umsprot version="1">
  <exec_rsp result="OK" diagnostic="Conexion Exitosa">
    <data name="SYSTEMMESSAGE">Error al Obtener Parametros
    Producto, intente nuevamente por favor.</data>
    <data name="ID_CODIGO">1</data>
    <data name="STATUS">ERROR</data>
  </exec_rsp>
</umsprot>

---

Errores de consulta de inventario

Terminal no asociado al usuario

El TERMINAL enviado no esta configurado para el USERID:

<umsprot version="1">
  <exec_rsp result="OK" diagnostic="Conexion Exitosa">
    <data name="SYSTEMMESSAGE">El terminal no se encuentra
    asignado al usuario.</data>
    <data name="STATUS">ERROR</data>
  </exec_rsp>
</umsprot>

Accion recomendada: verificar que el TERMINAL coincida con el dispositivo registrado para el usuario en la configuracion de Claro.

---

Recomendaciones de manejo

1. Distingue siempre errores HTTP del modulo, errores logicos de Claro y fallos de transporte.
2. Conserva raw_request_xml y raw_response_xml para auditoria y troubleshooting.
3. Trata timeout y fault como fallos reintentables solo si la idempotencia esta garantizada.
4. Si el webhook rechaza una factura, notifica con contexto suficiente para reprocesarla manualmente.
5. Implementa alertas cuando se repitan errores de IP, credenciales o mapping de producto.