Build a retry queue that respects Retry-After and action identity

Put retries in the same work record

A retry scheduler should update the original work item with its next eligible attempt time. Keep the saved action payload and idempotency identity alongside attempt count and last error code. A retry is a later delivery attempt for the same intent, so a new queue message must not accidentally become a new paid operation.

Lupin documents a request limit of 600 requests per minute per API key and returns Retry-After when that gate is exceeded. Workspace allowances and spending limits are separate. Creating more keys or workspaces to avoid a limit does not resolve the original account’s admission policy.

Interpret the delay before applying local policy

HTTP permits Retry-After to express either delay seconds or an HTTP date. Parse the recognized form conservatively and calculate when the server permits a later attempt. For a date, clock skew matters; maintain a synchronized worker clock and avoid turning a past or malformed value into an immediate retry storm.

Combine the server’s lower bound with your queue’s bounded backoff and jitter. The server delay should not be shortened by a local maximum sleep setting. If your worker cannot wait that long, persist a scheduled wakeup or surface the pending item instead of ignoring the header.

Classify before scheduling

A rate limit can justify waiting. A missing permission, invalid schema or payload conflict requires a different decision. A provider or persistence error can leave an outcome unknown, which requires inspecting the saved operation rather than blindly dispatching another side effect. Treat HTTP status, structured code and durable phase as complementary evidence.

Bound retry attempts and total elapsed time by the workflow’s deadline. A recurring queue that retries forever can outlive the user’s authorization or the relevance of its target. When the deadline expires, stop automatic dispatch and record the last known outcome, including any reservation that still requires reconciliation.

Control the aggregate retry load

Independent workers can each respect a delay and still wake together. Coordinate queue concurrency per credential and use jitter to spread eligible retries. Reserve throughput for read-only status inspection and cleanup so a pile of rejected creates cannot starve the calls needed to resolve them.

Webhook redelivery is another independent retry stream. Deduplicate it separately and avoid allowing one delivery to spawn unlimited client retries. A durable queue acknowledgment should mean your application stored work reliably, while external action completion remains a later state with its own evidence.

Verify time logic without calling a provider

Use a fake clock and stubbed HTTP responses to cover seconds, dates, missing headers, malformed values and a provider outage. Assert the scheduled timestamp, stable action identity and bounded attempt count. Advance simulated time instead of actually sleeping or issuing live requests.

Include two workers discovering the same eligible item and a worker that restarts after persisting the next attempt. The desired result is one claimed attempt, not one attempt per observer. Report these as local queue checks only; they do not establish the behavior of a real provider under load.

Sources & verification

Reviewed against the checked-in Lupin implementation and official reference documentation on 2026-11-05. Operational examples are illustrative; no live paid action, provider mutation or external message was executed.

• Lupin API rate limits ↗Checked 2026-11-05
• RFC 9110: HTTP Semantics ↗Checked 2026-11-05
• Lupin error reference ↗Checked 2026-11-05

Prepared with AI assistance by Lupin editorial. How we research and maintain these guides.