Rate limiting and quotas: protecting the API and the client

Rate limiting caps how many requests a client can make in a given period, and it protects both sides. It protects the bank, because a client that sends thousands of requests a second, whether by accident or by attack, could overwhelm the API and affect other clients. It protects the client, because a runaway process in the client's own system that calls the API in a loop will be stopped before it creates thousands of duplicate payment instructions. A rate limit is not a punishment; it is a safety control, and a well designed API makes the limit visible so the client can design around it. Source: API design guidance; bank API developer documentation; RFC 6585 and RFC 7807. The most common rate limiting model is the token bucket. Each client has a bucket that holds a number of tokens, and each request consumes one token. The bucket refills at a steady rate, for example 100 tokens per minute, up to a maximum, for example 1,000 tokens. A client that sends requests steadily never runs out, because the refill keeps up. A client that sends a burst of 1,000 requests in a minute empties the bucket and must wait for it to refill. This model is fair: it allows bursts, which are normal when a treasury system processes a batch of payments, but it prevents sustained overload. The bank sets the refill rate and the bucket size per client, based on the client's volume and the service level it has agreed. A corporate client that pays 500 suppliers every Friday needs a higher limit than a retail client that checks a balance twice a day. When a client exceeds the limit, the API returns HTTP 429 Too Many Requests, with a Retry-After header that tells the client how many seconds to wait before trying again. The response body should also carry a business error code, such as RATE_LIMITED, and a human readable message. The client must honour the Retry-After value: retrying immediately will fail again and may extend the block. For a business analyst, the requirement is to define this behaviour in the API specification, because the client builds against the specification and nothing else. A well behaved client implements exponential backoff: it waits the Retry-After period, and if it is limited again, it waits twice as long, then four times as long, up to a maximum. A client that ignores 429 responses and keeps hammering the API is a risk to the bank and to itself, and the bank may suspend its access. For a business analyst, the requirement is to define the limit per client type, the Retry-After behaviour, and the escalation path when a client is repeatedly limited. Quotas are different from rate limits: a quota caps the total number of requests or payments over a longer period, such as 100,000 requests per month or 10,000 payments per day. A quota protects the bank's capacity planning and the commercial agreement: a client that has agreed to 10,000 payments a day cannot send 50,000 without a new agreement. The API documentation must state this rule plainly, because a client that has to guess will guess wrong. When a client approaches its quota, the API should warn it, for example by returning the remaining quota in a response header, so the client can slow down or request an increase before it is blocked. A quota that is hit without warning is a poor experience, and a client that discovers it has hit its quota when a payment fails is a client that will complain. The API specification must state the quota, the warning threshold, and the error returned when the quota is exhausted. A client that is rate limited needs to know why and what to do. The 429 response should carry a Retry-After header with the number of seconds to wait, and a body with a business error code such as RATE_LIMITED and a message that states the limit that was exceeded, for example 100 requests per minute. The response should also carry headers showing the current usage, such as X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset, so the client can see how close it is to the limit and when the limit resets. A client that can see its usage can slow down before it is blocked; a client that cannot see its usage discovers the limit only when it is blocked. For a business analyst, the requirement is to define the rate limit headers, the Retry-After behaviour, and the usage information returned in each response. A test pack that does not cover this case will pass in the test environment and fail when a real client calls the API. Rate limiting must be fair across clients. A single client that sends a burst of requests must not consume the capacity that other clients need. The bank therefore applies limits per client, not globally, and it isolates clients so that one client's burst cannot affect another's. If a client is consistently hitting its limit, the bank should contact it to discuss a higher limit or a change in its integration pattern, rather than simply blocking it. A client that polls the status endpoint every second for a payment that takes an hour to settle is wasting its limit and the bank's capacity; the bank should suggest it use webhooks instead. For a business analyst, the requirement is to define the per client limits, the isolation mechanism, and the process for reviewing a client that repeatedly hits its limit. Further reading: API design guidance; RFC 6585; bank API developer documentation. Last reviewed 7 November 2026.