Rechazos HTTP en A2P SMS: cómo separar errores de integración de fallos de entrega

Qué significa —y qué no significa— una respuesta HTTP

Una respuesta HTTP informa del resultado del intercambio entre el cliente y el endpoint según la implementación de la API. No acredita por sí sola que el proveedor haya aceptado el SMS para procesamiento ni que el mensaje haya llegado al teléfono.

En una integración SMS conviene distinguir tres resultados: la respuesta del transporte HTTP, la aceptación o rechazo de la solicitud de envío por la API y los estados posteriores del mensaje. En SMPP, por ejemplo, los informes de entrega pueden comunicarse mediante mensajes deliver_sm o data_sm; son mecanismos distintos de la respuesta HTTP inicial.

El significado de cada respuesta depende del contrato de la API. Consulta la documentación oficial del proveedor para saber qué indica el código HTTP, qué confirma el cuerpo de respuesta y cómo obtener el estado posterior del mensaje.

Separa las etapas antes de diagnosticar

Modela el recorrido como etapas observables, no como un único resultado de «enviado» o «fallido». Esa separación evita atribuir a la red móvil un problema de autenticación o interpretar una aceptación técnica como entrega confirmada.

Transporte HTTP: determina si tu cliente pudo comunicarse con el endpoint y qué respuesta recibió. Un fallo de conexión o un timeout no demuestra que la API no haya procesado la solicitud.

Validación y aceptación: revisa la respuesta de la API según su documentación. Puede informar de una solicitud inválida, rechazada o aceptada para una etapa posterior; no supongas que todos los proveedores usan la misma estructura o semántica.

Estado posterior: consulta el mecanismo documentado para conocer el progreso o resultado del SMS, como un informe de entrega cuando esté disponible. Un DLR comunicado por la plataforma no debe describirse como una verificación independiente de la recepción en el terminal.

Registra el contexto mínimo para reconstruir el caso

Los campos de registro no son universales: el contrato de la API y las políticas de seguridad determinan qué datos existen y cuánto tiempo se conservan. Como base operativa, captura los elementos disponibles que permitan vincular la solicitud con la respuesta y con cualquier estado posterior.

Incluye la hora con zona horaria, el identificador de correlación de tu sistema y la referencia devuelta por la API, si existe. Conserva el método y endpoint utilizados, el código HTTP, el cuerpo de respuesta relevante y la versión de la integración.

Registra el destino en el formato normalizado que enviaste y los atributos técnicos necesarios para reproducir la solicitud, como el tipo de remitente o la codificación cuando formen parte de la API. Evita almacenar contenido o datos personales que no sean necesarios para el diagnóstico y aplica las reglas de acceso y retención de tu organización.

No confundas el identificador interno de tu aplicación con una referencia de mensaje del proveedor. Anota claramente qué sistema generó cada identificador.

• Hora y zona horaria del intento.
• Identificador de correlación interno y referencia del proveedor, si se devolvió.
• Destino normalizado, método y endpoint; protege los datos sensibles.
• Código HTTP, respuesta de la API y resultado de la operación según el contrato.
• Estado posterior disponible y hora en que se observó.

Clasifica la incidencia por etapa y evidencia

No conviertas una tabla genérica de códigos en un diagnóstico definitivo. Los rangos HTTP ofrecen contexto sobre la respuesta del servidor, pero la causa y la acción correcta deben verificarse en la documentación de la API y contrastarse con el cuerpo de respuesta.

Conectividad: si no hay respuesta HTTP, revisa la resolución del endpoint, la conexión desde el entorno emisor, los tiempos de espera y los registros disponibles en ambos extremos. La ausencia de respuesta no prueba que el servidor no recibiera la solicitud.

Autenticación y autorización: si la respuesta o el cuerpo señalan credenciales o permisos, confirma el mecanismo de autenticación, el entorno y los permisos configurados. No incluyas secretos en tickets ni registros compartidos.

Formato y validación: si la API rechaza parámetros, compara la solicitud con el esquema oficial: campos requeridos, formato del destino y restricciones documentadas. Corrige la solicitud antes de volver a enviarla.

Límites o políticas: si la documentación o la respuesta identifica un límite, una cuota o una restricción, confirma su alcance con el proveedor. No deduzcas una tasa permitida a partir de una respuesta aislada.

• Ubica primero la etapa donde aparece la evidencia: transporte, validación, aceptación o estado posterior.
• Interpreta juntos el código HTTP y el cuerpo de respuesta, no solo uno de ellos.
• Anota qué conclusión está confirmada y cuál sigue siendo una hipótesis.

Timeout: resultado incierto, no rechazo confirmado

Si el cliente agota el tiempo de espera, puede no saber si la solicitud llegó al servidor o si este la procesó antes de que se perdiera la respuesta. Sin una semántica de idempotencia documentada, el reenvío puede crear un segundo intento y, potencialmente, un mensaje duplicado.

Antes de reintentar, busca una referencia o consulta de estado que la API documente para esa operación. Revisa los registros del emisor y, si es posible, solicita al proveedor que compruebe si recibió la solicitud original. No inventes una clave de idempotencia ni asumas que repetir la llamada es inocuo.

• Sin respuesta y sin evidencia de recepción: clasifica el resultado como desconocido, no como rechazo probado.
• Respuesta explícita de rechazo, interpretada según la documentación: corrige la causa antes de intentar de nuevo.
• Aceptación confirmada, pero sin estado posterior: investiga la consulta de estado o el mecanismo de informes antes de enviar de nuevo.

Procedimiento de diagnóstico reproducible

Trabaja con un caso autorizado y controlado, respetando el consentimiento y las reglas aplicables al tráfico. El objetivo es aislar la etapa que falla, no aumentar el volumen ni probar destinos sin autorización.

1. Conserva la solicitud y la respuesta observadas, con credenciales y datos personales protegidos. Comprueba que el cliente no esté descartando el código HTTP o sustituyendo la respuesta por un mensaje genérico.

2. Consulta el contrato y la documentación oficial de la versión de API usada. Confirma el significado del código, los campos de respuesta, las referencias de mensaje, el mecanismo de estado y las reglas de reintento e idempotencia que estén documentadas.

3. Compara la solicitud real con una solicitud válida según el esquema publicado. Cambia una variable cada vez y reproduce solo mediante un flujo autorizado.

4. Correlaciona la hora y los identificadores con los registros del emisor y del proveedor. Distingue los hechos observados de las inferencias, por ejemplo, «HTTP recibido» frente a «mensaje aceptado» o «DLR recibido».

Decide entre corregir, reintentar o escalar

Corrige la integración cuando la evidencia y la documentación señalen credenciales, permisos, formato o parámetros incorrectos. No escales como un fallo de entrega algo que todavía no ha superado la validación de la API.

Reintenta solo cuando el contrato de la API y la evidencia permitan determinar que es seguro. Si la operación puede haberse procesado y no hay una garantía documentada contra duplicados, primero resuelve la incertidumbre mediante la referencia, la consulta de estado o el soporte del proveedor.

Escala cuando el problema persista con una solicitud conforme y autorizada, o cuando las evidencias sitúen la incidencia en el servicio o en una etapa posterior bajo responsabilidad del proveedor. Comparte hora, zona horaria, identificadores, endpoint, código HTTP y respuesta relevante; redacta secretos y limita los datos del destinatario a lo necesario.

• Corregir: rechazo atribuible a una solicitud o configuración que puedes verificar.
• Reintentar: solo con una regla documentada y sin duplicar un resultado incierto.
• Escalar: aportar evidencia correlacionable que ubique la incidencia fuera de la integración del emisor.

Qué no concluir de un 2xx, un error o la falta de DLR

Un HTTP 2xx no confirma automáticamente la entrega del SMS: puede indicar un resultado HTTP satisfactorio cuyo alcance exacto define la API. Comprueba si el cuerpo confirma aceptación y cómo se reportan los estados posteriores.

Una respuesta HTTP de error tampoco identifica por sí sola la causa final. Puede relacionarse con transporte, autenticación, validación u otra condición específica de la implementación; usa la respuesta y la documentación oficial.

La ausencia de un DLR no demuestra, por sí sola, ni entrega ni fallo. Determina si el informe está disponible, cuál es su significado en ese servicio y si existe información suficiente para asociarlo al mensaje. Separa siempre el estado comunicado por la plataforma de una confirmación independiente de recepción en el dispositivo.