Códigos de error SMPP en A2P SMS: guía operativa para reintentos, correcciones y cierres

Qué confirma —y qué no confirma— una respuesta a submit_sm

Una respuesta submit_sm_resp confirma el resultado de una solicitud en el protocolo SMPP. El campo command_status de la PDU de respuesta indica si el SMSC aceptó o rechazó esa petición SMPP y, cuando corresponde, devuelve un código de error.

Una aceptación técnica no equivale a entrega en el terminal. Si command_status indica éxito y el SMSC devuelve un message_id, el mensaje ha sido aceptado por ese sistema para su tratamiento posterior. No demuestra, por sí solo, que el mensaje haya alcanzado la red móvil, que haya sido entregado al dispositivo ni que el usuario lo haya visto.

La primera regla operativa es separar la aceptación de la presentación de la evidencia posterior de estado. Guarde el message_id devuelto por el SMSC junto con el identificador interno del mensaje, el destino, la ruta o conexión utilizada, la marca de tiempo y los parámetros relevantes de la PDU. Esa correlación será necesaria para interpretar DLR, query_sm, cancel_sm o replace_sm.

• submit_sm_resp con éxito: la solicitud SMPP fue aceptada por el SMSC.
• submit_sm_resp con error: la solicitud falló en esa etapa y debe clasificarse antes de reenviar.
• DLR o consulta de estado: aportan información posterior, pero no deben confundirse con una prueba independiente de recepción en el terminal.
• message_id: referencia técnica para operaciones SMPP posteriores y para correlación de eventos.

Las capas de estado en SMPP: sesión, aceptación del submit, DLR y evidencia de recepción

Una operación fiable necesita observar el ciclo de vida por capas. Primero está la sesión: conectividad de transporte y estado de bind. Después, la aceptación o rechazo de submit_sm. Más tarde, si se solicita mediante registered_delivery y la ruta lo soporta, puede llegar un recibo de entrega mediante deliver_sm o data_sm. Finalmente, cualquier evidencia de recepción independiente debe tratarse como una señal distinta de la telemetría del SMSC.

SMPP funciona sobre una conexión subyacente, habitualmente TCP/IP, de la que el protocolo espera transferencia fiable, control de flujo y manejo de errores de transporte. Una desconexión, un timeout o una respuesta que no llega no significan automáticamente que el SMSC no haya recibido la solicitud. En ese caso existe riesgo de presentación duplicada si se reenvía sin una estrategia de correlación e idempotencia en la aplicación.

El estado consultable mediante query_sm puede incluir ENROUTE, DELIVERED, EXPIRED, DELETED, UNDELIVERABLE, ACCEPTED, UNKNOWN y REJECTED. Estos estados deben conservarse tal como fueron recibidos, con el instante de observación y el contexto de la ruta. Un estado posterior puede cambiar la decisión inicial tomada tras submit_sm_resp.

• Sesión: conexión activa y bind válido para el tipo de operación.
• Aceptación: resultado de command_status en submit_sm_resp.
• Estado posterior: DLR o query_sm, cuando estén disponibles.
• Evidencia de recepción: no debe inferirse únicamente de una aceptación de submit_sm ni de un formato textual de DLR.

Por qué el mismo fallo no siempre merece la misma acción

La acción no debe depender solo del código. Un mismo error puede tener consecuencias distintas según el destino, el volumen afectado, la criticidad del mensaje, el estado de la sesión, la recurrencia y si existen cambios recientes de configuración. Un ESME_RTHROTTLED aislado pide reducir presión; una secuencia sostenida sobre toda la conexión exige revisar el control de ritmo y posiblemente pausar el flujo.

Defina una matriz de decisión que combine cuatro factores: clase del error, alcance, criticidad y evidencia disponible. Clasifique el alcance como mensaje individual, destino concreto, sesión, conexión o conjunto de tráfico. Distinga los mensajes que pueden expirar funcionalmente, como un OTP, de aquellos que admiten demora. No amplifique un problema temporal con reintentos simultáneos, y no convierta un error de datos en reintentos repetidos.

La política debe tener límites explícitos. Cada reintento necesita un contador, un intervalo de espera, una condición de salida y un mecanismo para evitar duplicados cuando la incertidumbre está en la respuesta de red. Cuando no hay respuesta concluyente, registre el caso como incierto en vez de etiquetarlo prematuramente como rechazado o entregado.

• Reintentar de forma controlada: solo ante señales temporales o ambiguas que justifiquen investigación.
• Corregir y reenviar: cuando el código indique parámetros, direccionamiento, credenciales o estado de bind incorrectos.
• Pausar y escalar: cuando el fallo afecte a una sesión, una cola, una capacidad o un volumen relevante.
• Cerrar: cuando el problema sea permanente, el mensaje pierda utilidad o se agoten los límites definidos por la política.

Taxonomía operativa de códigos y errores SMPP

La clasificación práctica debe conservar dos niveles: la semántica exacta de command_status y una categoría operativa interna. El primer nivel evita perder información. El segundo facilita automatización, alertas y decisiones consistentes.

Una taxonomía útil separa errores de construcción de PDU, sesión y autenticación, capacidad o limitación, direccionamiento, contenido o parámetros, y errores de sistema o proveedor. No todos los códigos estándares resuelven la causa raíz por sí solos; por ejemplo, ESME_RSYSERR solo se define como error de sistema y no especifica duración, origen ni reintentabilidad.

No sustituya el valor original por una etiqueta simplificada. Registre el código hexadecimal, el nombre SMPP si existe, la PDU implicada, el sequence_number, el command_status, el message_id cuando esté disponible, el sistema remoto, los parámetros no sensibles de direccionamiento y los eventos de sesión próximos al fallo.

• Construcción de PDU: corregir serialización, longitudes, campos y comando.
• Sesión y autenticación: restaurar bind y permisos antes de enviar tráfico.
• Capacidad: desacelerar, aplicar espera y vigilar la recuperación.
• Direccionamiento: normalizar los datos y validar la combinación de dirección, TON y NPI.
• Sistema o proveedor: preservar evidencia, limitar reintentos y solicitar una definición documentada si la semántica no es estándar.

Errores de sesión y bind: credenciales, permisos, modo de bind y salud de conexión

submit_sm solo puede emitirse desde una sesión en estado BOUND_TX o BOUND_TRX. Emitirlo desde otro estado puede producir ESME_RINVBNDSTS, definido como estado de bind incorrecto para el comando. La acción correcta no es reenviar inmediatamente el mismo submit: confirme el estado de la sesión, complete el bind adecuado y verifique que el modo autorizado permite transmisión.

Los errores ESME_RBINDFAIL, ESME_RINVPASWD y ESME_RINVSYSID corresponden a fallo de bind, contraseña inválida e identificador de sistema inválido. Deben tratarse como errores de corrección requerida. Reintentar con las mismas credenciales amplifica fallos y puede dificultar el diagnóstico.

Además del código, observe la salud de conexión: cierres de socket, timeouts, ausencia de respuesta, reconexiones frecuentes y eventos de unbind. Cuando una petición queda sin respuesta por una incidencia de transporte, no asuma que no fue procesada. Antes de repetirla, aplique controles de deduplicación y, si están disponibles y son apropiados, mecanismos de consulta o reconciliación basados en los identificadores conocidos.

• Verifique que la sesión esté enlazada como transmisora o transceptora antes de enviar submit_sm.
• Compruebe system_id, contraseña, permisos y modo de bind con la configuración autorizada.
• Diferencie un rechazo SMPP explícito de un timeout o desconexión sin respuesta.
• No reprograme en paralelo mensajes inciertos tras un fallo de transporte sin una estrategia contra duplicados.

Errores temporales: congestión, límites, capacidad y espera controlada

ESME_RTHROTTLED, código 0x00000058, indica que el ESME ha excedido los límites de mensajes permitidos. Debe interpretarse como una señal para reducir el ritmo de envío. El reintento inmediato, especialmente desde varios procesos en paralelo, mantiene o agrava el exceso que originó el rechazo.

ESME_RMSGQFUL, código 0x00000014, indica una cola de mensajes llena. Clasifíquelo como señal de capacidad del SMSC o de la ruta, separada de los errores de formato, credenciales o direccionamiento. Puede ser transitorio, pero el estándar no fija una ventana de recuperación ni garantiza que un reintento vaya a tener éxito.

Aplique espera progresiva y un límite de reintentos coherente con la utilidad del mensaje. Reduzca la concurrencia o el caudal antes de reintentar. Mida por separado los rechazos por limitación, el tiempo hasta la recuperación y el alcance por conexión o destino. Si persisten los errores, pause el tráfico afectado y abra una investigación con registros completos.

• ESME_RTHROTTLED: reducir ritmo, controlar concurrencia y reintentar tras espera.
• ESME_RMSGQFUL: tratar como limitación de capacidad y vigilar si se recupera.
• Evite reintentos simultáneos y sin límite.
• Detenga los reintentos cuando el mensaje haya dejado de ser útil, se alcance el máximo definido o la incidencia requiera escalado.
• ESME_RSYSERR: investigar primero; el estándar no permite concluir por sí solo que sea temporal o reintentable.

Errores permanentes o de corrección requerida: parámetros inválidos, direccionamiento, remitente y formato

Los errores de PDU exigen revisar la construcción del mensaje antes de una nueva presentación. ESME_RINVMSGLEN indica longitud de mensaje inválida; ESME_RINVCMDLEN, longitud de comando inválida; y ESME_RINVCMDID, identificador de comando inválido. No son candidatos para un reintento idéntico: requieren corregir la serialización o la lógica de integración.

En submit_sm, short_message admite hasta 254 octetos. La especificación advierte que el límite físico exacto puede variar según la red subyacente. Para mensajes superiores a 254 octetos debe utilizarse message_payload y no debe usarse short_message simultáneamente. Este requisito no sustituye la validación de las reglas aceptadas por el SMSC para codificación, segmentación y otros parámetros.

ESME_RINVSRCADR y ESME_RINVDSTADR indican dirección de origen y destino inválidas, respectivamente. También existen ESME_RINVDSTTON y ESME_RINVDSTNPI para TON y NPI del destino. Revise la dirección como un conjunto: valor, TON, NPI y regla de aceptación de la conexión. E.164 es una referencia internacional de numeración, pero una apariencia compatible con esa referencia no garantiza que la combinación de dirección, TON, NPI y política del SMSC sea aceptada.

Para los remitentes, aplique la misma prudencia: un error de dirección de origen requiere revisar el valor enviado y los parámetros asociados, además de las reglas de la conexión. No intente sortear restricciones de remitente o políticas de mensajería; corrija la configuración y confirme los requisitos aplicables a la ruta.

• ESME_RINVMSGLEN, ESME_RINVCMDLEN y ESME_RINVCMDID: corregir la PDU; no repetir sin cambios.
• ESME_RINVSRCADR y ESME_RINVDSTADR: revisar valor de origen o destino.
• ESME_RINVDSTTON y ESME_RINVDSTNPI: revisar la combinación de dirección, TON y NPI.
• Para mensajes largos, no combine short_message con message_payload.
• Mantenga validación previa al envío para reducir rechazos evitables.

Errores ambiguos o específicos del proveedor: conservar evidencia y pedir una definición documentada

No todo código recibido tiene una semántica universal. SMPP reserva rangos para extensiones y para proveedores de SMSC. Si recibe un código fuera de la tabla estándar, no lo reasigne a una causa genérica ni lo traduzca como entrega fallida sin documentación. Registre el valor exacto y solicite al sistema remoto una definición técnica documentada.

Los recibos de entrega también requieren cautela. SMPP permite que el SMSC devuelva un delivery receipt mediante deliver_sm o data_sm cuando se ha solicitado con registered_delivery, pero el contenido textual informativo de un SMSC Delivery Receipt es específico del proveedor. No construya automatizaciones críticas basadas únicamente en una cadena textual asumida como universal.

Cuando esté presente, network_error_code representa un código real de error de red específico de la tecnología. Conserve tanto el tipo de red como el valor del código, además del estado SMPP y del texto original del DLR. Esta evidencia permite investigar sin borrar la distinción entre una semántica SMPP estándar, un estado reportado por el SMSC y un código de red subyacente.

Un buen expediente de escalado incluye cronología, PDU y respuesta relevantes, códigos originales, identificadores correlacionados, estado de sesión, porcentaje y alcance de fallos, destinos afectados de forma minimizada cuando sea necesario, y cambios recientes de configuración. Evite incluir credenciales o datos innecesarios.

• Conserve command_status en hexadecimal y su interpretación estándar cuando exista.
• Registre textos de DLR sin asumir que su formato es portable entre sistemas.
• Preserve network_error_code con su tipo de red y valor original.
• Solicite documentación para códigos de extensión o de proveedor.
• Escalone con evidencia técnica suficiente y sin exponer secretos de conexión.