¿Cómo evito enviar el mismo SMS dos veces?

Una conexión puede caerse después de que Bird acepta un SMS pero antes de que tu aplicación reciba la respuesta. Reintentar con una clave nueva puede crear un segundo envío porque Bird lo trata como una solicitud distinta.

¿Cómo funciona la clave?

Establece un encabezado Idempotency-Key para cada envío SMS previsto y reutilízalo al reintentar la solicitud idéntica. La garantía de aceptación exactamente una vez significa que los reintentos coincidentes durante tres horas deben resolverse en el mismo envío aceptado, aunque hayas perdido su respuesta.

Por ejemplo, una confirmación de pedido conserva la misma clave a lo largo de un timeout y su reintento. Una confirmación para un pedido diferente recibe una clave diferente.

Las respuestas repetidas incluyen Idempotency-Replay: true, lo que permite a tus logs distinguir una repetición de una solicitud recién procesada.

Las claves SMS están limitadas a tu espacio de trabajo. Bird retiene las respuestas completadas durante tres horas según su contrato de idempotencia. Después de esa ventana, la misma clave puede ejecutar una solicitud nueva porque su registro de repetición ha expirado. Por tanto, un reintento un día después requiere conciliar el resultado original antes de enviar de nuevo.

¿Qué me dicen las respuestas de error?

El código de error distingue una solicitud modificada, una solicitud sin terminar y una protección no disponible.

• 409 con E01005 IdempotencyKeyReuse: la misma clave se usó para una solicitud diferente. Corrige la asignación de clave antes de reintentar, ya que esta clave pertenece a la solicitud original. Bird compara el método, el endpoint, la ruta y los parámetros de consulta, y el cuerpo crudo. Incluso un cambio de espacio en blanco JSON hace que la solicitud sea diferente.
• 409 con E01004 RequestInProgress: una solicitud concurrente con la misma clave no ha terminado. Espera brevemente y reintenta con la misma clave y solicitud para que la original pueda completarse.
• 503 con E01033 IdempotencyUnavailable: la protección no estaba disponible antes de la ejecución, por lo que este intento no se ejecutó. Reintenta con backoff usando la misma clave y solicitud. Esta respuesta no establece el resultado de un intento anterior.
• Otras respuestas 5xx o timeouts: reintenta con backoff usando la misma clave y solicitud. La garantía de aceptación exactamente una vez cubre estos reintentos durante tres horas. Detente cuando agotes tu límite de reintentos.

El encabezado de idempotencia preserva la identidad de la solicitud a lo largo de estos reintentos.

¿La clave garantiza que no haya duplicados?

La garantía es la aceptación exactamente una vez de solicitudes idénticas con la misma clave en el mismo espacio de trabajo durante tres horas. Esos reintentos deben resolverse en un único envío aceptado, incluso si se perdió una respuesta. Consulta el estado del mensaje para confirmar la entrega.

Pasada la ventana de retención de tres horas, la clave original puede identificar una operación nueva. Si desconoces el resultado original, concílialo antes de volver a enviar.

Conserva los registros de eventos y envíos de tu aplicación para que puedas conciliar un resultado incierto antes de enviar de nuevo. Incluye el número de pedido o referencia en el mensaje para que el destinatario pueda reconocer a qué evento corresponde.

¿Qué pasa con un mensaje que el teléfono muestra dos veces?

Una clave de idempotencia controla los reintentos de API; no controla cómo el teléfono del destinatario muestra un mensaje. Una captura de pantalla por sí sola no establece dónde se originó un duplicado.

Compara el log completo de envíos de tu aplicación con los registros de mensajes de Bird. Varios IDs de mensaje aceptados pueden confirmar varios envíos. Encontrar un solo ID en un log incompleto no prueba que el duplicado ocurrió aguas abajo. Incluye los IDs relevantes, el destino y las marcas de tiempo cuando solicites al soporte que investigue.

¿Qué debo hacer?

1. Asigna una clave a cada envío SMS previsto y reutiliza la solicitud idéntica en sus reintentos.
2. Reintenta errores de red, timeouts y respuestas 5xx con backoff, conservando la clave y la solicitud idéntica durante tres horas.
3. Corrige los conflictos de solicitudes modificadas y retrasa los reintentos cuando la solicitud original sigue en curso.
4. Deja sin resolver los reintentos agotados o expirados hasta que concilies su resultado, antes de decidir si procede otro envío.