Name shed order before the API throttles you.
When the API starts saying no, someone has already chosen what to drop. Better if that choice was written down before the peak.
Before a partner API throttles you in production, fill a TWIMCO Backpressure Policy Card: budget per caller, shed order under pressure, what you never drop, how you signal wait, and who owns the throttle. A retry loop without a shed order is how you amplify a limit.
The 429 is not your policy
Peak hour hits. A marketplace partner returns 429. Your workers retry. The retries queue behind each other. Catalog sync still runs. Search indexing still runs. Checkout capture waits behind a bulk job that could have waited. Customers see spin. You see a dashboard that says the partner is “rate limited,” as if that sentence were a plan.
The partner’s limit is a fact about their door. Your backpressure policy is a fact about which of your jobs get to keep knocking, which wait, and which you shed on purpose so the ones that matter still land.
Walk this once before the next peak. Not as architecture theater—as a tabletop with the people who own the callers. Bring the last 429 graph if you have one. Bring the job names. Leave with a filled card, not with “we should be more careful.”
This note walks the TWIMCO Backpressure Policy Card—one page for one upstream (or one shared budget across a few callers). Fill it before the next peak, not during it. The filled card is the asset. Copy the fields. Do not invent a success rate to make the sheet look measured.
Marketplace and partner-heavy surfaces live and die on this shape. When the product is a market with many dependent calls, the offer home is marketplaces. Keep the card about your shed order.
Walk the card once, with one upstream
Bring one real upstream into the room. Not every integration. The one that already returned 429, or the one you know will.
Upstream and budget. Name the partner and the limit unit they publish—or the unit you observe. Requests per minute, concurrent connections, payload weight. If they publish nothing useful, write “observed only” and the number you will treat as the ceiling until they say otherwise. Do not invent a ceiling to look precise.
Callers that share the budget. List every job, service, and human tool that spends against that door. If you cannot list them, you cannot shed on purpose. Someone’s laptop script will surprise you.
Never-shed paths. The calls that must keep a lane even when everything else waits: capture, cancel, refund confirmation, safety stop—whatever your operation cannot postpone. If everything is “never shed,” you do not have a policy. You have a wish.
Shed order. The sequence of work you stop or delay first. Bulk catalog refresh before live inventory read. Analytics export before offer accept. Background reindex before checkout pricing. Write the order as verbs your on-call recognizes.
Wait signal. What a shed or delayed caller does: queue with a visible lag, return a typed “try later” to the UI, skip this cycle and leave a gap marker. Silent drop is not a wait signal. Silent drop is how you discover missing data on Monday.
Retry rule. Bound retries. Name backoff. Name when retry is forbidden because the shed already decided this work waits. Unlimited retry against a 429 is how you become the spike.
Throttle owner. The role who may tighten the shed order during an event, who may open a never-shed exception, and who declares the event over. A channel without a role will debate while the queue grows.
Probe. How you know the upstream is accepting work again—and how you know your shed is still on when it should be. “Error rate looks better” needs a named check.
Walk these lines out loud. Where two people disagree, keep the stricter shed until someone owns a change.
How the work moves
Walk the card under a fake ceiling
- Name the budget
Partner limit unit, published or observed.
- List spenders
Every job and tool that hits the door.
- Lock never-shed
The few paths that keep a lane.
- Order the shed
What stops first, second, third.
- Bound the retry
Wait signal, backoff, and who may reopen.
If you have not named what you will shed, the rate limit will choose for you.
Shed first, then argue about fairness
Under pressure, fairness debates arrive late. The card forces the unfairness into daylight before the event.
A bulk job and a customer-facing write share a token bucket. Without shed order, the bulk job’s concurrency wins because it was tuned for throughput last quarter. With shed order, the bulk job’s concurrency collapses first by policy, and the write keeps a reserved lane. That feels unfair to the analytics owner until you say out loud what a stalled checkout costs. The card is where that trade is recorded, not argued in the incident channel.
A partner returns Retry-After. Your client ignores it and uses a fixed half-second loop. The wait-signal and retry lines exist so Retry-After becomes part of the policy, not a header you log and forget. If the partner sends no Retry-After, your card still names a default wait—and names who may override it during an event.
A second team adds a new reporter that hits the same API key. Nobody updates the caller list. Peak day, the reporter eats the budget. The callers line on the card is a living list; a new spender amends the card before go-live. Treat an unsigned spender like an unsigned deploy.
You will be tempted to solve this only with more quota. More quota helps until the next feature. Shed order helps every time the ceiling is real. Buy capacity when you should—and still fill the card so the new ceiling has a policy attached.
These are delivery-shaped composites from marketplace and partner work, not telemetry from a named client and not a claim about any partner’s SLA.
Refuse the “just retry” culture
A few habits look responsible and make limits worse.
Every failure retries three times with no jitter, in every worker, at once. You turn one throttle into a stampede. Bound retry and stagger it, or the shed never gets a chance to matter.
Someone raises the partner’s contracted tier and leaves shed order blank. More budget without a policy just moves the cliff. Buy capacity and still fill the card.
On-call disables the rate limiter “temporarily” so a backlog clears. The never-shed list was empty, so everything stampeded. Temporary becomes the new default until the next incident review. If you must break glass, write the exception on the card with an expiry and an owner—then put the limiter back.
A status page says “degraded” while your UI still offers actions that will fail. Wait signal belongs in the product path, not only in the ops channel. A button that queues with a clear “try again in a few minutes” is policy. A button that spins until timeout is how you teach customers to refresh harder.
If you recognize these, fill the Backpressure Policy Card and wire the shed before the next peak window. A card that sits in a doc folder is still better than nothing—and it is not the same as an enforced order.
Decision guide
Retry culture versus policy
| Consideration | Under pressure, improvised | Card is filled |
|---|---|---|
| Who spends | Unknown scripts appear at peak. | Caller list is complete and amended on change. |
| What stops first | Whatever fails loudest. | Shed order written before the event. |
| Customer path | Competes with bulk jobs. | Never-shed lane reserved. |
| Retries | Unbounded stampede. | Bounded, respects wait signals. |
Put this into practice
- Pick one upstream that already throttles you, or will. Open a TWIMCO Backpressure Policy Card.
- List callers, never-shed paths, shed order, wait signal, retry bound, and throttle owner.
- Rehearse the shed in a staging twin or a quiet hour: force a low budget and watch which work stops first.
- Amend the card when a new spender appears. No spender without a line.
- If the product is a marketplace surface that depends on partner APIs under load, bring the card into scoping for marketplaces.
The rate limit is the partner’s door. The shed order is yours.
Related work: Spin:Market.
We build alongside the people doing the work.
Bring us the problem you’re thinking about.