Request Strategies
Handle network failures gracefully with automatic retries and idempotency keys to prevent duplicate charges and ensure reliable payment processing.
Network requests fail. async-stripe provides a robust RequestStrategy API to handle idempotency keys and retries automatically, ensuring your application handles transient failures gracefully without double-charging customers.
Strategy Options
The library implements the "Full Jitter" exponential backoff algorithm recommended by Stripe engineering to prevent thundering herd problems.
| Strategy | Description | Use Case |
|---|---|---|
Once | Fire and forget. No retries. | You are handling retries manually |
Idempotent(key) | Fire once with a specific, user-provided Idempotency Key | Critical payment creation flows where you need control over the idempotency key |
Retry(n) | Retry n times with a random UUID idempotency key | General retry logic without backoff |
ExponentialBackoff(n) | Retry n times with exponential backoff (0.5s base, up to 8s max) and randomized jitter | Recommended for production to handle transient failures gracefully |
Usage
You can apply a strategy globally to the client (for all requests) or override it on a per-request basis.
Global Client Strategy
pub async fn run_strategy_example() -> Result<(), StripeError> {
let secret_key = std::env::var("STRIPE_SECRET_KEY").expect("Missing STRIPE_SECRET_KEY in env");
let client = ClientBuilder::new(secret_key)
.request_strategy(RequestStrategy::idempotent_with_uuid())
.build()?;
let first_page = ListCustomer::new().send(&client).await?;
println!(
"first page of customers: {:#?}",
first_page.data.iter().map(|c| c.name.as_ref().unwrap()).collect::<Vec<_>>()
);
Ok(())
}Per-Request Strategy
);
Ok(())
}
pub async fn per_request_strategy_example(client: &Client) -> Result<(), StripeError> {
let params = CreateCustomer::new();
let customer = params
.customize() // Enter builder mode
.request_strategy(RequestStrategy::Retry(5)) // Override strategy for this call only
.send(client)
.await?;Have feedback? Let us know here