What causes "Stripe API rate limit reached, retry {}/{} after {} ms" in apache/seatunnel?

Increase the rate-limit max retries option so bursts of 429s are absorbed.

Stripe API rate limit reached, retry {}/{} after {} ms

Error message

Stripe API rate limit reached, retry {}/{} after {} ms

What it means

StripeSourceReader wraps API calls in executeWithRateLimitRetry. When the Stripe API returns HTTP 429 (Too Many Requests) and retries remain, it logs this warning, computes an exponential backoff delay, sleeps, and retries the request. It is an informational retry notice, not a fatal error; it becomes an error only when rateLimitMaxRetries is exhausted, at which point the 429 response is returned to the caller.

Source

Thrown at seatunnel-connectors-v2/connector-http/connector-http-stripe/src/main/java/org/apache/seatunnel/connectors/seatunnel/stripe/source/StripeSourceReader.java:171

    private HttpResponse executeWithRateLimitRetry() throws Exception {
        int retries = 0;
        while (true) {
            HttpResponse response =
                    httpClient.execute(
                            sourceParameter.getUrl(),
                            sourceParameter.getMethod().getMethod(),
                            sourceParameter.getHeaders(),
                            sourceParameter.getParams(),
                            sourceParameter.getBody(),
                            sourceParameter.isKeepParamsAsForm());
            if (response.getCode() != HTTP_TOO_MANY_REQUESTS
                    || retries >= sourceParameter.getRateLimitMaxRetries()) {
                return response;
            }
            retries++;
            long backoffMillis = calculateBackoffMillis(retries);
            log.warn(
                    "Stripe API rate limit reached, retry {}/{} after {} ms",
                    retries,
                    sourceParameter.getRateLimitMaxRetries(),
                    backoffMillis);
            try {
                sleeper.sleep(backoffMillis);
            } catch (InterruptedException e) {
                Thread.currentThread().interrupt();
                throw new HttpConnectorException(
                        HttpConnectorErrorCode.REQUEST_FAILED,
                        "Interrupted while waiting to retry Stripe request",
                        e);
            }
        }
    }

    @VisibleForTesting
    long calculateBackoffMillis(int retryNumber) {

View on GitHub (pinned to cf67b549a7)

Solutions

Increase the rate-limit max retries option so bursts of 429s are absorbed.
Reduce source read parallelism or split size to lower request rate.
Check calculateBackoffMillis settings/jitter to spread requests.
Use a dedicated Stripe API key for the sync job to avoid contention with other consumers.
Handle the returned 429 response after exhaustion — schedule the job during off-peak hours or in smaller windows.

Example fix

// before
sourceParameter.getRateLimitMaxRetries() == 3
// after
// raise retries and lower parallelism to stay under Stripe limits
"rate_limit_max_retries" = 10, parallelism = 1

Defensive patterns

Strategy: retry

Validate before calling

// ensure sane retry config before job start
if (rateLimitMaxRetries <= 0 || rateLimitMaxRetries > 20) {
    throw new IllegalArgumentException("rate_limit_max_retries must be in (0, 20]");
}

Try / catch

Response response = executeWithRateLimitRetry(request);
if (response.getCode() == 429) {
    // retries exhausted: back off long-term and re-run later
    throw new IOException("Stripe rate limit persists after max retries");
}

Prevention

Set rate_limit_max_retries generously (e.g., 10+) for Stripe sources.
Run one job per API key; avoid sharing keys across concurrent jobs.
Schedule large historical backfills off-peak.
Keep source parallelism low (Stripe limits are per-key, not per-worker).
Alert on recurring 'Stripe API rate limit reached' warnings to catch sustained 429s early.

When it happens

Trigger: Stripe API responds with HTTP status 429 while retries < rateLimitMaxRetries inside executeWithRateLimitRetry (invoked from the source reader's response handling).

Common situations: High-volume historical backfills exceeding Stripe's per-key rate limits; multiple concurrent SeaTunnel jobs sharing one Stripe API key; rateLimitMaxRetries configured too low for sustained 429s.

Related errors

AI-assisted analysis of apache/seatunnel@cf67b549a7 (2026-09-10). Data as JSON: /api/errors/208bffc99846f2b2. Report an issue: GitHub.