Stripe recuerda tu solicitud cuando la respuesta desaparece

Lo que cubre este video

• La idempotencia se refiere al efecto deseado de repetir una operación. La API v1 de Stripe añade un contrato documentado de reproducción de respuesta guardada.
• Un reintento de la misma acción lógica utiliza la misma clave y parámetros. Persiste la clave de operación a través de 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 errores 500, y devuelve esa respuesta guardada en los reintentos.
• Los parámetros cambiados con la misma clave producen una falta de coincidencia. Los fallos de validación y los conflictos de ejecución concurrente no guardan ningún resultado idempotente para ese intento y pueden reintentarse.
• 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 concilia 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; usa el objeto relevante, la solicitud del Dashboard y los webhooks para establecer su resultado.
• La API v2 utiliza una semántica de reproducción diferente. Una clave no establece una entrega universal exactamente una vez para el correo electrónico, el 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 son 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 compra 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, entre bastidores.

¿Qué identifica una clave de idempotencia?

0:21 La 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 comprar un café. Stripe completa tu solicitud de pago, y la respuesta se pierde al regresar a casa. El cliente ve un "spinner". Su banco puede tener una interpretación más emocionante. Una solicitud de creación desprotegida puede repetir el efecto secundario.

¿Cómo la misma clave hace 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, preserva esa clave con la operación en tus registros. Para la API de la versión uno de Stripe, una vez que comienza la ejecución del endpoint, el estado y el cuerpo de la primera solicitud se guardan. Envía la misma clave y parámetros de nuevo, y Stripe devuelve la respuesta guardada. El café se queda donde está mientras su recibo viaja de nuevo.

¿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 asistente de reintentos con nombre optimista. El cliente toca de nuevo. Tu aplicación decide si eso reanuda la compra pendiente o inicia otra nueva. Un café genuinamente nuevo obtiene una nueva clave. Una clave nueva para cada reintento de red anula la protección.

1:27 Parámetros diferentes con la misma clave activan una falta de coincidencia.

¿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 está en ejecución, Stripe no guarda ningún resultado idempotente para ese intento. Esas solicitudes pueden reintentarse. Una solicitud en carrera genera 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 alcance 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 concilia 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 problema.

¿Por qué un error recordado puede seguir regresando?

2:20 Una respuesta de error quinientos 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 usando objetos, el Dashboard y los 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 reintento con este contrato?

2:39 Veredicto, entre bastidores. SHIP IT. Yo implementaría claves estables con reintentos y conciliación limitados, 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 con responsabilidad.

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