AI & Automation

API Rate Limits for Business Integrations: Set a Retry Budget Before the Queue Grows

The next scheduled run arrives while the previous run is still waiting to retry.

Both runs need the same source. Neither has a complete result. The queue keeps growing because the integration has a waiting rule and no stopping rule.

Give a read operation a retry budget before it enters that queue. State how many attempts it gets, how long it may remain active, and who owns the incomplete result.

The worksheet below proposes a bounded policy for read requests. All records, times, thresholds, and business examples are synthetic. It excludes writes, webhook delivery, and live account operations.

Classify the Failure Before Choosing a Delay

A rate-limit response needs a different decision from a permission failure. Retrying every error with the same timer hides that distinction.

HTTP 429 identifies rate limiting and may include Retry-After. The standard leaves request counting and user identification to the server. RFC 6585, section 4.

For the proposed worksheet, assign a response to one of five classes: accepted read, documented quota rejection, authentication or permission failure, eligible temporary failure, or unknown result.

Require evidence for the class. Record the status, relevant safe headers, provider error code, and documentation reference. Keep credentials and sensitive response bodies out of ordinary diagnostic logs.

A 401 indicates invalid or missing authentication for the target resource. A 503 describes temporary unavailability. Neither status guarantees a later attempt will succeed. RFC 9110, authentication, service unavailability.

Under this policy, an authentication failure stops automatic retries and goes to the access owner. A documented temporary failure can enter the bounded retry path. An unfamiliar response goes to review.

Keep the classification narrow. Do not turn a generic forbidden response into a quota diagnosis without provider evidence. The API-first operations design needs a response contract for each connection it depends on.

Separate Provider Waiting Rules From Local Backoff

Retry-After can contain an HTTP-date or a nonnegative integer delay in seconds. The integer counts from response receipt. RFC 9110, section 10.2.3.

For a synthetic response received at 09:00:00 UTC, Retry-After: 45 yields 09:00:45 as the earliest time under that delay. An HTTP-date specifying 09:00:45 UTC identifies that instant directly.

Record the raw safe header and the interpreted instant. Mark a malformed value unresolved. A reviewer should see whether the next attempt came from provider guidance or a locally chosen fallback.

A documented reset timestamp is another provider input. A guessed pause is a local policy choice. Keep separate fields for them even when they produce the same next-attempt time.

For this proposed policy, choose the latest applicable provider time and local backoff time. Add only a nonnegative scheduling margin. Never shorten a provider wait to fit a local deadline.

If the provider's earliest permitted time falls beyond the budget, stop the run. The deadline decides whether the run may continue. It does not grant permission to make an earlier request.

Use elapsed time for the active-run budget. Record UTC instants for the receipt. Define how the implementation handles clock uncertainty when interpreting an absolute HTTP-date. Hold a request when the permitted instant remains unclear.

Put GitHub's Rules Beside the GitHub Connection

GitHub REST rate limits can produce 403 or 429. Its troubleshooting guide distinguishes a primary limit using zero x-ratelimit-remaining and a secondary limit using the error message. GitHub rate-limit errors.

GitHub's best-practice sequence uses retry-after when present, the UTC epoch-seconds x-ratelimit-reset when remaining quota is zero, and otherwise at least one minute. For continued secondary-limit failures, GitHub recommends exponentially increasing waits and stopping after a specific number of retries. GitHub REST API best practices.

Those names, units, and fallback belong to GitHub's guidance checked on the source date. Reopen the relevant documentation for the provider and endpoint you use. Do not copy GitHub's minute-long fallback into an unrelated connection and call it a requirement.

For a GitHub worksheet, reference both classification evidence and the waiting rule selected. When several applicable constraints appear, the proposed policy preserves the later time. Ambiguous or contradictory evidence goes to the integration owner.

Record the provider and API version in the connection configuration. Keep any version-independent general guidance labeled as such. This article's synthetic endpoint below is not a GitHub endpoint or a simulation of GitHub quota allocation.

Define Four Bounds Before the First Attempt

Use four controls for one read operation: attempt limit, elapsed deadline, local backoff cap, and maximum accepted queue age.

The attempt limit counts the initial request. A limit of four means one initial attempt and at most three retries. Write that definition beside the number so two maintainers cannot interpret it differently.

The elapsed deadline limits the entire active operation, including waits and requests. Check it before waiting, before sending, and while a request is in flight. Reserve time for validating and retaining a successful response.

The local backoff cap limits delays invented by your policy. It never caps a longer provider-required wait. For an illustrative policy, local delays grow from fifteen to thirty to sixty seconds, with sixty as the local cap.

Maximum accepted queue age limits how long uncompleted work may remain unresolved before owner review. Measure age from the original enqueue time. A retry does not create younger work.

Choose values from the business use, provider contract, and available runtime. The example values demonstrate arithmetic. They are not recommended defaults for all integrations.

Assign an owner to each terminal condition. A run stopped by its deadline needs a recorded outcome even if another scheduled appointment is near. Silence should not become the queue's only failure signal.

Walk Through a Run That Stops Before Overlap

Consider a fictional read that prepares a local inventory draft every five minutes. Its next appointment is 09:05 UTC. No real endpoint is called.

The job enters the queue at 08:59:30. It starts at 09:00:00. The proposed active deadline is 09:04:00, leaving a minute before the next appointment. Maximum attempts are four, including the first.

For this example, requests complete immediately at the listed response times. Actual request durations would consume the same deadline. Queue age is the interval since 08:59:30.

UTC time Attempt or decision Synthetic evidence Remaining budget and outcome
09:00:00 Attempt one 429, Retry-After 60 Three attempts remain; wait until at least 09:01:00
09:01:00 Attempt two 503, Retry-After 120 Two attempts remain; wait until at least 09:03:00
09:03:00 Attempt three 429, Retry-After 180 One attempt remains, but next permitted time is 09:06:00
09:03:00 Stop decision 09:06:00 exceeds 09:04:00 deadline Stop now; current read incomplete; owner review required

At the stop decision, active elapsed time is three minutes. Queue age is three minutes thirty seconds. One minute remains before the deadline, and two minutes remain before the next appointment.

The attempt budget still has room. The deadline does not. Record the specific stopping reason rather than claiming that all attempts were exhausted.

The locally capped backoff cannot turn the final three-minute provider delay into sixty seconds. Its role is limited to locally chosen waits. In this example, each provider delay exceeds the applicable local backoff.

Carry the Waiting Boundary Across Scheduled Runs

Stopping the first run does not erase the provider wait. Store the known not-before instant with the connection's controlled scheduling state.

At 09:05, the next appointment checks that state before sending anything. The synthetic provider restriction still extends to 09:06. Under this proposed scheduling policy, the appointment records a deferred state and sends no request.

The example uses a single active reader for this connection. A later appointment cannot create a competing worker while an existing operation owns the same work. Assign that ownership explicitly in the implementation.

Preserve the original enqueue time for unresolved work. If a later appointment resumes the same required read, its age continues from 08:59:30. Do not reset age by renaming the task.

If business policy allows a newer request to replace obsolete work, record that decision and its scope. A current snapshot request may serve a different purpose from a required historical interval. Avoid merging them by assumption.

Use the missed-job recovery worksheet to decide which appointments may be skipped, caught up, or backfilled. A retry timer cannot make that business decision.

Preserve Incomplete Reads and Accepted Checkpoints

For the fictional inventory, the last accepted local projection remains unchanged after the stopped run. Its freshness label continues to identify the earlier accepted observation.

Retain the failed run's identifier and safe response evidence. If it collected part of a larger read, identify which portion reached accepted storage. Leave the overall read incomplete until its completion rule is satisfied.

Under the proposed policy, no error or exhausted retry budget advances a synchronization checkpoint. A checkpoint needs the workflow's own evidence that required data reached its destination.

The stopped state should name its cause: deadline prevents another permitted attempt. It should also name the prior accepted projection and the next required decision. Avoid reducing that record to “job finished.”

Map the recovery owner through the business system dependency map. The person who can repair access may differ from the person accepting a stale report. Give each decision to the appropriate owner.

Keep diagnostics proportionate. A safe provider request identifier, status, and timing interpretation can support review without copying private source records into an alert.

Copy the Retry Decision Worksheet

Use one row per response decision. The worksheet fields are proposed operating records. They do not replace endpoint documentation.

Field What to record Synthetic third-attempt entry
Work identity Resource, configuration, original enqueue instant Inventory read Q17; enqueued 08:59:30 UTC
Status and classification Status, safe error code, supporting provider rule 429; documented quota rejection
Provider header Raw safe value and interpreted boundary Retry-After 180; not before 09:06:00
Next permitted attempt Later of provider boundary and local delay 09:06:00 UTC
Remaining budget Attempts left, deadline, active elapsed time One left; deadline 09:04:00; elapsed three minutes
Queue age Time since original enqueue Three minutes thirty seconds
Owner Role responsible for the unresolved condition Integration owner with operations backup
Terminal outcome Accepted, deferred, stopped, or review required Stopped; deadline would be exceeded; checkpoint unchanged

Before adopting the policy, ask a receiver to recompute the example without reading the outcome column. Check the header interpretation, remaining attempts, deadline comparison, and queue age separately.

Then ask what happens at the next appointment. The answer needs the persisted waiting boundary as well as the stopped-run record. A clean terminal state for one worker should leave the next worker enough evidence to wait responsibly.

Stop with a readable reason.

Sources

Topic map: APIs, webhooks, and automation

Articles in this cluster, then the 3 clusters that share the most topics with it.

This cluster: APIs, webhooks, and automation

Neighbor: CRM and pipeline data

Neighbor: Spreadsheets, CSV files, and data handoffs

Neighbor: Records, access, and continuity