Broker connection errors

Broker problems cluster into a handful of shapes. Start from the symptom:

401 unauthorized: broker rejected your keys

The keys are wrong: a paste typo, a pair revoked at Alpaca, or paper keys in the live slot (and vice versa; Alpaca’s paper and live systems each reject the other’s keys). Regenerate at Alpaca, re-paste both halves into the matching environment card, and save. Saving re-runs the automatic connection test against Alpaca before anything is stored.

Keys that stopped working

Keys that worked when you saved them can stop working later: you regenerated or revoked the pair at Alpaca, or Alpaca closed or reset the account. SleeveFolio notices the next time it talks to that account — its regular background check, a daily automatic run, or an order you place — when Alpaca answers “401 unauthorized” (or a 403 “forbidden” when SleeveFolio is only reading your account). From then on, until you save working keys for that account:

• A warning banner across the top of every screen says Alpaca refused your saved paper keys (or live), with a Reconnect button that opens Settings → Broker.
• You get one alert, in the app and by email (the Broker connection row on the Notifications page) — once when it starts, not on every check.
• New orders on that account are refused before anything is sent, with a message that names the fix, and automatic trading sits out its runs there (the run’s notification and the Strategies page say why).
• Background checks of that account stop retrying and are logged as failed checks in your audit log; on your live account that also pauses live orders (see Live orders need a recent check).

Your holdings at Alpaca are untouched. The kill switch stays on screen as always and Pause works (it is SleeveFolio’s own switch), but Alpaca refuses Cancel open and Liquidate on that account too while the keys are dead (the result names the account that failed), so manage anything urgent from Alpaca’s own dashboard meanwhile. The fix is the same as above: generate a fresh pair at Alpaca and save it in Settings → Broker. The banner and the order block lift the moment the save passes its connection test (on your live account, live orders then also wait for the next successful check); if Alpaca starts accepting the old keys again on its own, they lift at the next check.

A 403 on an order is different: it is Alpaca turning down that one order on its merits (not enough buying power, a stock that can’t take fractional shares, a day-trading restriction), and the order is marked rejected with Alpaca’s reason while your keys stay connected.

Already connected to another SleeveFolio account

Each Alpaca account (your paper account and your live account count separately) can be connected to only one SleeveFolio account at a time, so two SleeveFolio sign-ins can never trade the same money. Saving keys for an Alpaca account that another SleeveFolio account already uses is refused with this message, and nothing is stored. To move the Alpaca account over, sign in to the SleeveFolio account that has it and disconnect those keys in Settings → Broker (deleting that account frees them too), then save them here. Otherwise, use keys from a different Alpaca account.

429 rate-limited: too many requests too fast

Too many requests in a window, usually transient. A scheduled background sync that hits a 429 is automatically retried a few times before it gives up, so a brief spike clears on its own. A page you are looking at does not retry a 429 — the limit is counted per minute, so trying again immediately would only add to it — and reloading a moment later is the right move. If you see it persistently, something else is hammering the same Alpaca account’s limits (another bot or script using the same keys is the classic cause, so give SleeveFolio its own key pair).

Timeouts

Alpaca or the network. Requests that only read data (your balances, positions, and order history) are retried automatically a couple of times, all within about a second, so a momentary hiccup never reaches the screen — an error you actually see is an outage that outlasted them. Placing and canceling orders are deliberately not retried: a retry could place the same order twice, so those are attempted once and reported to you.

Check Alpaca’s status page; re-paste both halves into the matching environment card in Settings → Broker and hit Test + save once it’s green: saving re-runs the connection test against Alpaca. The automatic check that compares SleeveFolio’s records with Alpaca’s (every 15 minutes while your account is in use, about once an hour otherwise) catches them up once the outage ends.

After fixing

Re-save the keys (Test + save), then check the Reconciliation page. A drift item (a recorded mismatch between SleeveFolio’s records and the broker’s) from the gap is normal; investigate and acknowledge it once you’ve confirmed the records match again.