API throttling is the control an API provider applies to slow down, queue or reject requests once a client exceeds its allowed rate, stopping one heavy user from degrading service for everyone. Payment APIs sit in front of card network connections, bank gateways, fraud engines and ledgers, so limits are set per API key or account, often stricter on reporting endpoints. Algorithms such as token bucket or sliding window count requests; refusals return HTTP 429 with a Retry-After header. Where teams distinguish the terms, rate limiting is the hard cap and throttling the traffic shaping around it. A reporting job sharing a key with live charges can break checkout, so clients retry with exponential backoff.
What is API throttling in payments
Payment APIs sit in front of systems with hard capacity limits: card network connections, bank gateways, fraud engines and ledgers. A provider serving thousands of merchants cannot let one merchant's bulk job consume all of that capacity during peak trading. Throttling rules are therefore set per API key or per account, often with separate limits for live and test traffic and stricter limits on expensive endpoints such as search or reporting.
How does API throttling work
The provider counts each client's requests over time using an algorithm such as a token bucket, a leaky bucket, a fixed window or a sliding window. In a token bucket, a client receives tokens at a steady rate, each request spends one, and a full bucket allows short bursts. When the bucket is empty, the next request is delayed or refused.
A refused request normally returns HTTP status 429 Too Many Requests, often with a `Retry-After` header stating how many seconds to wait. Many APIs also return headers showing the limit, the remaining allowance and the reset time, so a well-built client can slow itself down before it hits the ceiling.
API throttling vs rate limiting
The two terms are used loosely and often interchangeably. Where teams do distinguish them, rate limiting is the hard cap (for example 100 requests per second, with request 101 rejected) and throttling is the broader behaviour of shaping traffic once a client approaches or crosses that cap, which can include queueing requests, adding delay or reducing priority instead of rejecting outright. Rate limiting is the rule; throttling is how the system enforces it.
A throttling incident in practice
A marketplace runs its month-end reconciliation by requesting 180,000 transaction records one at a time from its PSP at 300 requests per second. The PSP's reporting limit is 25 requests per second. Within seconds most calls return 429, and because the same API key also creates live charges, checkout starts failing too. Switching to the PSP's downloadable reconciliation file or a paginated list endpoint, and using a separate restricted key for reporting, removes the conflict.
Handling throttled requests safely
Clients should retry 429 responses with exponential backoff and jitter, as part of their retry logic, rather than immediately repeating the call. Payment creation requests need an idempotency key so a retry after a timeout never charges the customer twice. For a buyer reviewing a payment platform, the throttling limits in its own acquirer and banking contracts show how much volume growth it can absorb before re-engineering.