Paginación y claves de idempotencia en la API de Stripe: starting_after, has_more y la ventana de 24 horas

Qué es

La referencia de paginación de Stripe describe métodos de listado que "comparten una estructura común y aceptan, como mínimo... limit, starting_after y ending_before", con "paginación basada en cursor... Ambos parámetros aceptan el ID de un objeto existente... y devuelven los objetos en orden cronológico inverso", y establece que los dos parámetros de cursor "son mutuamente excluyentes". Toda respuesta de listado envuelve los resultados como {"object": "list", "data": [...], "has_more": bool, "url": "..."}, con limit en 10 por defecto y un máximo de 100. Además, las bibliotecas cliente de Stripe ofrecen "auxiliares de autopaginación para recorrer todas las páginas de un listado", de modo que rara vez hace falta avanzar manualmente con starting_after. Para las escrituras, la referencia de idempotencia de Stripe explica que la cabecera Idempotency-Key permite al cliente "repetir la solicitud con seguridad, sin riesgo de crear un segundo objeto ni de aplicar la actualización dos veces", porque Stripe "guarda el código de estado y el cuerpo resultantes de la primera solicitud... independientemente de si tiene éxito o falla". Las claves guardadas pueden eliminarse cuando tienen al menos 24 horas de antigüedad (una clave reutilizada después se trata como una solicitud nueva), y una respuesta reproducida incluye Idempotent-Replayed: true. Reutilizar una clave con parámetros distintos se rechaza: "la capa de idempotencia compara los parámetros entrantes con los de la solicitud original y devuelve un error si no coinciden". Los resultados solo se guardan cuando un endpoint empieza a ejecutarse, por lo que una solicitud que falló en la validación o que colisionó con otra concurrente puede reintentarse con la misma clave. La página de límites de tasa de Stripe indica un límite global de 100 solicitudes por segundo en modo live y 25 en un sandbox, 25 por segundo por endpoint salvo que se indique otra cosa, y 20 solicitudes de lectura por segundo para la Search API. Las solicitudes limitadas reciben 429 más una cabecera Stripe-Rate-Limited-Reason (global-rate, endpoint-rate, global-concurrency, endpoint-concurrency o resource-specific). Un 429 sin esa cabecera no es un límite de tasa: puede ser un lock_timeout sobre un objeto que otra solicitud mantiene bloqueado.

Por qué importa

La paginación por desplazamiento (offset) no se ofrece en absoluto en los endpoints de listado v1 de Stripe, así que cualquier intento del cliente de calcular un número de página no funcionará. Las claves de idempotencia son la forma documentada de que reintentar un POST (tras un timeout o una conexión caída) no cree un cargo o un cliente duplicado.

Cómo aplicarlo

• Lee has_more, no el número de elementos devueltos, para decidir si hay que pedir otra página; pasa el id del último elemento como starting_after.
• Prefiere el iterador de autopaginación integrado en la biblioteca cliente a los bucles escritos a mano.
• Genera una clave de idempotencia nueva (Stripe sugiere un UUID v4) por cada intento lógico de escritura, y reutiliza la misma clave solo al reintentar exactamente la misma solicitud tras un fallo de red.
• Mantén las claves de idempotencia libres de datos sensibles y con un máximo de 255 caracteres, según las restricciones de Stripe.
• Ante un 429, aplica un retroceso exponencial con jitter y lee Stripe-Rate-Limited-Reason; nunca aumentes la concurrencia para compensar. No hagas pruebas de carga contra un sandbox, cuyos límites son inferiores a los del modo live.

Trampas

Reutilizar una clave de idempotencia en solicitudes realmente distintas "por seguridad": Stripe trata la discrepancia de parámetros como un error, no la deja pasar en silencio. Enviar claves de idempotencia en GET/DELETE, lo cual, según la documentación de Stripe, no tiene efecto, porque esos métodos ya son idempotentes por definición.