Rate-limit integrations without hiding important failures

An integration can look healthy because its worker keeps retrying. Meanwhile, invoices or updates wait longer than the business can accept. A useful rate-limit design manages demand and preserves evidence about why work did not complete. It should not relabel every failure as temporary throttling.

Read the provider’s signals precisely

OWASP recommends the 429 Too Many Requests response when API requests arrive too quickly.[7] Providers may also define additional limit signals. GitHub documents handling for primary and secondary limits and gives specific response-header guidance.[6] Do not copy one provider’s interpretation into every integration.

Record the response status, safe error type, relevant quota headers, and operation category. A 403 can require a permission correction rather than a delayed retry.[7] Use the provider’s documented response details to distinguish those cases. Keep the original failure visible when the scheduler postpones another attempt.

Control admission before exhaustion

Recommend a shared scheduler for calls that consume the same provider quota. Separate customer-facing work from bulk synchronization where their priorities differ. Reserve capacity deliberately instead of allowing a large backfill to consume every available request.

Use bounded concurrency and a queue with observable age. Decide whether limits apply per credential, tenant, endpoint, or another documented scope. If workers share a quota, coordinate their budget rather than assigning each worker the full allowance. Queueing absorbs a burst only while storage and acceptable delay remain available. Define what happens when that capacity runs out.

If the queue reaches its limit, choose an explicit admission response or a controlled pause. Quietly discarding work makes later reconciliation harder to explain.

Stop retries from hiding incidents

GitHub advises waiting according to its retry-after header when present and eventually reporting an error after bounded retries for continued secondary-limit failures.[6] Match your policy to that provider guidance. Treat repeated authentication failures, validation errors, and unsupported operations as separate work that needs correction.

• Track quota consumption and the age of the oldest queued business item.
• Preserve provider status and error details after internal rescheduling.
• Bound attempts and route exhausted work to an owned exception queue.
• Test bulk-load contention and recovery after the provider resets capacity.

Hypothetical example: a catalog synchronization

Hypothetical example: a distributor imports product updates while sales staff submit urgent stock checks. The team assigns separate priorities within one shared provider budget. A quota response delays catalog work, but a revoked credential raises an immediate configuration incident.

The dashboard shows both queue age and the last successful catalog checkpoint. This prevents a quiet retry loop from looking like successful progress. Priority handling adds scheduling complexity and can starve bulk work unless the policy reserves some capacity for it. Start by listing which business items can wait, then set a visible delay threshold for each class.