feat(brokers): retry robinhood GETs on 429 and 5xx, never POSTs

[eaitbrahim]

Closes #411. Unblocked by #419 — see the POST section.

The gap

Robinhood allows 100 req/min sustained, 300 burst, and the transport had no backoff at all: a 429 propagated as a bare HTTPError alongside 401 and 5xx.

The limit is reachable in ordinary use, not just under abuse. get_fee_summary alone can spend 21 requests in one call (_MAX_PAGES + the account read), and preview_order now adds a trading_pairs read on top (#418). A "wait half a second" was turning into a failed cycle.

What retries

GET, 429 / 500 / 502 / 503 / 504	retried, up to 4 attempts, 0.5s doubling, capped at 8s
GET, 404	not retried — it is an answer, and the 404→None split stays as load-bearing as ever
GET, 401	not retried — a signature or clock problem does not heal in half a second; retrying turns one clear failure into four identical ones
POST, anything	never retried — see below

Retry-After wins where the venue sends one, since it knows when its window resets and we do not — but it is clamped, not obeyed. Retry-After: 3600 is a legal response, and honouring it literally would park a trading loop for an hour inside what the caller believes is a bounded read.

Only the delta-seconds form is read. The HTTP-date form is legal and deliberately ignored: honouring it means trusting the server's clock against ours, and a skewed clock gives either an instant retry (useless) or a very long sleep (worse), while exponential backoff is already correct without any clock at all.

A retryable status that survives every attempt still raises, so a persistent quota problem stays visible rather than becoming a hang.

Why a POST is never retried

This is the decision, not the unfinished part.

A 429 or 5xx on create_order is an unknown outcome, not a refusal — the venue may have accepted the order before the response was lost. Sending it again places a second live order unless both attempts carry the same client_order_id, and this layer cannot tell whether they would: the body arrives already built, and an id derived from a caller's idempotency key (#409) is indistinguishable from a freshly minted uuid4 from here.

Now that #409 exists, a caller can make a placement retry safe. So the retry belongs where that knowledge lives — above the adapter, not inside the transport. A transport that retried POSTs would be guessing, on the one request where guessing costs money.

test_a_POST_IS_NEVER_RETRIED_even_on_a_429 asserts one call and zero sleeps, with the reason in the docstring.

Signing moved inside the loop

The signature is valid for 30 seconds from its timestamp. A retry that waited out a backoff and presented the first attempt's signature would come back 401 — a failure invented by retrying, and indistinguishable from a bad credential.

Pinned by a test that advances the clock between attempts, because two attempts in the same wall-clock second sign identically and would prove nothing.

Testability

sleep is injected, and _transport() in the tests defaults it to a no-op. Without that, every existing test touching a 429 or 5xx would have waited out real backoff — the first run of this change took 11.8s instead of 1.3s for exactly that reason.

No jitter: jitter exists to desynchronise many clients retrying in lockstep, and this is one process making one request at a time against one account. Noted in the docstring so the reasoning expires visibly if that ever changes.

Still true, and still in the README

Backoff is not throttling. The aggregate rate is still unbounded, and get_fee_summary's 1 + N sweep should be called on a schedule, not per order.

Full suite: 3777 passed, 3 skipped. ruff check and mypy (190 files) clean.

🤖 Generated with Claude Code