Rate Limiting

Overview

Understand the idea

Rate limiting restricts how frequently an API client or network identity may call a service. It protects shared capacity against accidental request storms, inefficient polling and abuse. A limit might apply per API key, IP address, endpoint, account or time window. The relevant limit is provider-specific and may vary for reads, invoice creation and payout operations.

What actually happens

A server tracks consumption using a token bucket, leaky bucket, fixed window or similar mechanism and rejects or delays requests that exceed policy. Clients should read documented quota headers and back off after a 429 response, using jitter rather than making every worker retry at the same instant. Repeated retries should retain idempotency context; otherwise an ambiguous timeout can become duplicate invoice or payout creation. Asynchronous webhooks can reduce the need to poll for every status change.

In a distributed application, a shared limiter should coordinate usage across app servers instead of counting only requests seen by one process. Exponential backoff with jitter reduces synchronized retry spikes, and a circuit breaker can stop storming a provider during a wider outage. Rate-limit failures for safe GET requests may be retried more freely than state-changing payout commands, which need idempotency and status reconciliation. A sensible operational dashboard distinguishes quota exhaustion from network errors and invalid credentials so teams do not apply the wrong fix.

Decisions and failure cases

A 429 response means the request was rate-limited under a particular policy, not necessarily that authentication failed or a blockchain transaction failed. Do not hardcode an unverified numeric limit; follow actual provider documentation and respect retry-after guidance. Rate limits are not a substitute for authorization checks.

Related concepts

Idempotency Key, API Authentication, Webhook Deduplication.

Further reading

Stripe API rate limits.