Stripe recuerda tu solicitud cuando la respuesta desaparece

Qué cubre este vídeo

• La idempotencia se refiere al efecto deseado de repetir una operación. La API v1 de Stripe añade un contrato documentado de repetición de respuestas guardadas.
• Un reintento de la misma acción lógica utiliza la misma clave y parámetros. Persiste la clave de operación en llamadas SDK separadas o reinicios de aplicaciones; una acción genuinamente nueva necesita su propia clave.
• Después de que comienza la ejecución del endpoint, la API v1 de Stripe guarda el estado y el cuerpo de la primera solicitud, incluyendo los errores 500, y devuelve esa respuesta guardada en los reintentos.
• Los parámetros cambiados con la misma clave producen una discrepancia. Los fallos de validación y los conflictos de ejecución concurrente no guardan ningún resultado idempotente para ese intento y pueden ser reintentados.
• Stripe retiene las claves de la API v1 durante al menos 24 horas y puede eliminarlas después. Limita los reintentos de red no resueltos a las primeras 24 horas, luego detente y reconcilia antes de repetir la operación.
• Un error 500 en caché puede seguir reproduciéndose después de que se recupere la conectividad. La operación original puede tener efectos secundarios; utiliza el objeto relevante, la solicitud del Panel de Control y los webhooks para establecer su resultado.
• La API v2 utiliza una semántica de repetición diferente. Una clave no establece una entrega universal exactamente una vez para correo electrónico, inventario y cada operación de base de datos local.

Transcripción traducida

Traducido de la narración original en inglés. El audio y los subtítulos disponibles están controlados por YouTube.

¿Un tiempo de espera canceló tu pago?

0:00 Crees que un tiempo de espera significa que tu pago falló. El servidor puede terminar mientras la respuesta desaparece, dejando tu pago mostrando absolutamente nada. ¿Por qué un reintento puede cobrar de nuevo? ¿Cómo recuerda Stripe un intento? ¿Cuándo deberías dejar de reintentar? Y ten en cuenta un detalle desagradable. Un error recordado puede sobrevivir al problema de red.

0:17 Volveremos a eso. Esto es The Daily Diff, bajo el capó.

¿Qué identifica una clave de idempotencia?

0:21 Idempotencia significa que repetir una operación tiene el mismo efecto deseado que hacerla una vez. Una clave de idempotencia etiqueta una acción lógica. La versión uno de la API de Stripe reconoce esa etiqueta en los reintentos y reproduce una respuesta guardada. Imagina que compras un café. Stripe completa tu solicitud de pago, y la respuesta se pierde al regresar a casa. El cliente ve un indicador de carga. Su banco podría tener una interpretación más emocionante. Una solicitud de creación desprotegida puede repetir el efecto secundario.

¿Cómo hace la misma clave que un reintento sea seguro?

0:45 Adjunta una clave única antes del primer intento y guárdala para los reintentos. Si tu aplicación se reinicia, conserva esa clave con la operación en tus registros. Para la API versión uno de Stripe, una vez que comienza la ejecución del endpoint, se guardan el estado y el cuerpo de la primera solicitud. Envía la misma clave y los mismos parámetros de nuevo, y Stripe devuelve la respuesta guardada. El café se queda donde está mientras el recibo vuelve a viajar.

¿Qué guarda exactamente Stripe?

1:07 Aquí está la redacción real de Stripe. Los reintentos con la misma clave devuelven la respuesta guardada, incluyendo errores quinientos. La documentación hace más trabajo que tu ayudante de reintentos con un nombre optimista. El cliente vuelve a tocar. Tu aplicación decide si eso reanuda la compra pendiente o inicia otra nueva. Un café genuinamente nuevo obtiene una clave nueva. Una clave nueva para cada reintento de red anula la protección.

1:27 Diferentes parámetros con la misma clave desencadenan una discrepancia.

¿Qué sucede cuando la solicitud cambia?

1:30 Si los parámetros fallan la validación, o si otra solicitud con esa clave todavía se está ejecutando, Stripe no guarda ningún resultado idempotente para ese intento. Esas solicitudes pueden ser reintentadas. Una solicitud de carrera obtiene un conflicto. Estas son las reglas de la versión uno. La versión dos se comporta de manera diferente. Un encabezado no puede prometer una entrega exactamente una vez en todo tu sistema. El correo electrónico, el inventario y tu base de datos necesitan manejo de fallos.

1:52 La clave protege la operación dentro de su ámbito documentado. Stripe retiene las claves de la versión uno durante al menos veinticuatro horas y puede eliminarlas

¿Cuánto tiempo es seguro reintentar el resultado recordado?

1:59 después. Una clave eliminada puede ejecutar una nueva solicitud. Mantén los reintentos no resueltos dentro del primer día. Más allá de eso, detente y reconcilia el resultado original. Usa retroceso exponencial y "jitter" para darle un respiro al servidor. De lo contrario, los reintentos forman una cola fuera de una cafetería en llamas. Las bibliotecas de Stripe manejan los reintentos, pero verifica los valores predeterminados de tu biblioteca. Ese error persistente es el truco.

¿Por qué un error recordado puede seguir apareciendo?

2:20 Una respuesta 500 en caché sigue reproduciéndose después de que se recupera la conectividad. La operación original puede haber producido efectos secundarios. Resuelve su resultado utilizando objetos, el Panel de Control y webhooks. Una nueva clave puede repetir la acción. Si prefieres leer esto que oírme decirlo, el "diff" llega a tu bandeja de entrada cada mañana, gratis en the daily diff dot dev, enlace abajo.

¿Implementaría un botón de reintentar con este contrato?

2:39 Veredicto, bajo el capó. SHIP IT. Enviaría claves estables con reintentos acotados y reconciliación, para que los clientes obtengan café sin financiar tu educación en sistemas distribuidos. Y ese es el "diff" de hoy. Soy Niko de Axrisi. Fusiona responsablemente.

Fuentes

1. Idempotent requestsStripe Docs
2. Designing robust and predictable APIs with idempotencyStripe Engineering — Brandur Leach
3. Advanced error handlingStripe Docs
4. HTTP Semantics — RFC 9110 §9.2.2 Idempotent MethodsIETF / RFC Editor