API rate limits: read a supplied contract before retrying
By Ai Flowi · Published
An API rate limit restricts how much request activity a caller may perform within a defined scope and period. To handle it, read the supplied limit contract: what is counted, who shares the allowance, when capacity becomes available and which requests may be repeated. A quota response alone cannot establish that a write is safe to retry.
API throttling is the enforcement behavior that slows or refuses activity beyond a policy. A request allowance, an in-flight concurrency ceiling and a usage charge answer different questions. Do not turn a provider’s unspecified policy into a guessed requests-per-minute number.
How do I write down the counting contract for an API rate limit?
Start with the unit. A policy might count requests, records or another resource. It may apply to one credential, one account, an endpoint or a shared organization. Identify that scope before calculating headroom: two callers using the same allowance cannot each spend the remaining capacity independently.
| Contract field | Example-defined value | Why it matters |
|---|---|---|
| Scope | One synthetic account shared by two callers | Combine both callers’ activity. |
| Allowance | 100 request attempts | Count attempts, including rejected attempts. |
| Window | Fixed 60-second interval aligned to the service clock | Only the stated interval boundaries reset this allowance. |
| Over-limit behavior | 429; rejected before application work | This synthetic contract explicitly rules out an effect for that rejection. |
| Timing signal | A field named wait_seconds in the error body | In this example it reports the minimum wait to the next boundary. |
| Retry responsibility | The calling application | One place tracks attempts and decides whether to send again. |
Every name, number and rule in this table is authored for education. It is not a vendor default or an AI Flowi service policy. A real contract may use a rolling window, replenished capacity or a different rejection rule. Never apply this fixed-window calculation to those mechanisms unchanged.
Work the 90-plus-15 request example
At one observation point, the account has already made 90 attempts in the current window. A second caller proposes 15 more attempts before that window ends. The combined total would be 105, which exceeds the fictional allowance by five. There is room for ten further attempts under the supplied policy, assuming no other activity intervenes.
Allowance: 100 attempts
Already counted: 90 attempts
Proposed: 15 attempts
Remaining before proposal: 10 attempts
Excess if all are sent in this window: 5 attemptsThe caller can defer five attempts and schedule the remaining ten only if it can coordinate the shared account’s activity. Sending all 15 does not produce 15 accepted operations: this example rejects the five attempts beyond the threshold. Their rejection does not restore capacity, because the fictional policy counts attempts.
A snapshot showing ten remaining is not a reservation. If the first caller continues, fewer than ten may be available by the time the second caller sends. Record the observation time and account scope alongside the number; otherwise a precise calculation can still support an incorrect dispatch decision.
Separate quota availability from retry safety
429 Too Many Requests identifies a rate-limiting response, but the destination’s contract must explain its accounting and effect semantics. In this example, the five rejected attempts consume allowance without performing application work. A new window changes their capacity position; it does not turn a different request with an unknown outcome into a confirmed rejection.
| Observation | Operation evidence | Decision to record |
|---|---|---|
| Fictional 429 before processing | The supplied example contract says no effect occurred | Wait as specified; send only within a bounded attempt policy. |
| Read response unavailable | The endpoint contract defines a safe read with no business side effect | A bounded repeat can be considered after capacity and timing checks. |
| Write response unavailable | Completion is unknown | Hold replay until reconciliation or an applicable idempotency contract resolves the uncertainty. |
| Write with a supported idempotency key | Scope, retention, payload matching and concurrent behavior are documented | Repeat only within those rules, retaining the same business-operation identity. |
| Write already confirmed at destination | The intended effect is present and matches the request | Record completion; additional capacity is not a reason to repeat it. |
For the investigation that resolves an uncertain write, follow the failed-write runbook example before putting that operation into a quota retry queue.
Suppose the second caller defers five attempts and the next window opens. Those five now compete with fresh work from both callers; they are not an additional allowance on top of the new 100-attempt budget. Mark each as deferred, sent or abandoned so that moving it between windows cannot accidentally enqueue it twice. Keep the original proposed operation separate from its subsequent attempts: the quota counts sends, while the work queue tracks operations.
Read timing signals without inventing defaults
If a provider supplies a response header or body field for retry timing, use its documented meaning and units. Do not assume an unfamiliar value is seconds, a timestamp or the number of requests remaining. A timing signal can indicate when another attempt may be considered without promising that the next attempt will succeed.
When there is no usable signal, consult the approved caller policy instead of adding an unlimited loop. Record a maximum attempt count or deadline, the delay policy and the final unresolved state. Exponential backoff increases delays after failures; jitter varies dispatch timing. Those are caller-policy concepts here, not claims of a native workflow feature.
The documented AI Flowi Workflow boundary
Status: documented. Consult the API Request component reference for request setup; its catalogue interface is documented in the catalogue; not production-tested by Ai Flowi
.
example configuration, not a recorded test
For the fictional policy, map an inspected response to a quota observation containing the account scope, observation time, counted-attempt unit and applicable window. When a rejection includes the example’s wait_seconds field, retain its value with that observation. This is a caller worksheet, not an assumed component envelope: locate the body in the actual response before reading the field.
A response received after the window boundary can describe an attempt counted in the previous window. Associate it with the attempt’s service-side window evidence rather than the time the caller happened to inspect it. If that evidence is absent, mark the window uncertain and avoid subtracting its count from a new allowance. The resulting record should explain which budget the attempt used and why a deferred operation became eligible.
Access requires the selected API’s account and key when it uses them, with that provider billing you separately. No quota scheduler or backoff execution was exercised through AI Flowi Workflow for this example.
Common mistakes and stop conditions
- Budgeting separately for callers that share one account allowance.
- Treating a limit observation as reserved capacity.
- Retrying in both the sender and workflow without one attempt ledger.
- Repeating an uncertain write after the clock resets.
- Using an unbounded retry loop to hide an unresolved quota or permission problem.
Do not use the example policy when the counting scope, timing rule or write outcome is unknown. Keep the operation pending and obtain the missing contract or destination evidence. Related reading: HTTP status codes, API pagination for multi-request collections, and API testing for separate response and effect checks.