¿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?

Estableces un encabezado Idempotency-Key para cada envío SMS previsto y lo reutilizas al reintentar la solicitud idéntica. Cuando Bird retiene la respuesta original, un reintento coincidente devuelve esa respuesta sin ejecutar el envío de nuevo.

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. El bloqueo en vuelo expira en 30 segundos. La expiración no establece si el envío original surtió efecto.
• 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. Bird no retiene las respuestas 5xx. Un reintento repite una respuesta exitosa retenida o puede ejecutarse de nuevo si no se retuvo ninguna respuesta.

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

¿La clave garantiza que no haya duplicados?

La clave reduce los envíos duplicados, pero no garantiza una sola ejecución.

Un envío puede surtir efecto antes de que Bird retenga su respuesta. Si la retención de la respuesta falla o el bloqueo en vuelo expira, un reintento puede ejecutar el envío de nuevo. La ventana de retención de tres horas también limita la protección de repetición.

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 para mantener cualquier protección de repetición disponible.
3. Corrige los conflictos de solicitudes modificadas y retrasa los reintentos cuando la solicitud original sigue en curso.
4. Concilia los envíos inciertos, incluidos los que superan la ventana de repetición de tres horas, antes de decidir si otro envío es apropiado.