When the connection test fails
Each red fix card the Connect wizard can show after Test connection: what Alpaca or the trading server actually said, whether it is about your keys, and the one thing to do.
- Who it is for
- New to Bellwether
- Reading time
- 7 min read
- Updated
When Test connection on Connect your broker does not end in "Connection works", the paste card comes back with a red fix card: a title in plain words, what to do, and one button. The server's exact sentence is folded under "Error details (for whoever runs your desk)" so you can pass it on without having to understand it. This page lists every card, what produced it, and whether your keys are the problem. Two rules of thumb: only two cards ever ask you to make new keys, and a card that says "operator" is never about anything you typed.
Before anything is sent
Three mistakes are caught under the field as you paste, so they never reach the server:
- A space or line break inside the Key ID or the Secret Key. Copy it again from Alpaca.
- A Key ID that starts with AK. That is a live-account key and this deployment trades paper only. Switch the Alpaca dashboard to Paper and generate keys there; paper Key IDs start with PK. (If a live pair reaches the trading service some other way, it is detected and parked; see the second card below.)
- A Key ID that starts with CK. That is an OAuth app's client id, not an account key. Open the Paper dashboard's Your API Keys box instead.
The fix cards
| Card | What actually happened | About your keys? | Do this |
|---|---|---|---|
| Alpaca did not accept this key pair | The trading service tried the pair against Alpaca's paper endpoint and then its live one, and both answered "not authorised" (or a pair that used to work was refused mid-session). Usually one of three things: a character lost while copying; the Secret Key belongs to an older pair (pressing Generate New Keys retires the previous pair immediately); or the two values swapped | Yes | Open Alpaca keys, generate a fresh pair on the Paper dashboard, copy both values straight from the box, paste, press I pasted a new pair, then Test connection |
| These keys belong to a | The trading service detected a real-money account behind the pair. This deployment trades paper only, so the connection was labelled live and parked (trading off); nothing was placed and nothing will be. The book's owner also gets an alert saying so | Yes | Paper tab, new pair (PK…), paste again. Going live is a deploy-time ceremony, never a paste |
| Both values are needed, exactly as Alpaca shows them | One box was empty, or a value had a space in it when it reached the API | Yes (a paste slip) | Paste the API Key ID and the Secret Key, one in each box; the Key ID is the shorter one and starts with PK |
| Could not reach Alpaca just now | A timeout, a network error or a 5xx from Alpaca while the trading service asked for the account | No | Wait a moment and press Try again; it re-tests the pair already stored, nothing to re-paste |
| Alpaca asked us to slow down | Alpaca rate-limited the trading server | No | Wait a minute, Try again later |
| The trading server could not get through to Alpaca | Alpaca turned the request away before looking at the keys, with no Alpaca error code; in practice a network rule (egress proxy / allowlist) between the trading server and Alpaca | No | Tell your operator and hand them the Error details line; press Try again later once they have looked. Your keys are very probably fine |
| This one is on Bellwether's side, not yours | The trading server (or the API) is missing a piece of its own setup (it has no key to open or store sealed credentials, or the stored blob could not be opened), so it never even tried Alpaca | No | Tell your operator; nothing to redo. Try again later re-tests once they say it is fixed |
| This book already has a connection | A connection is already saved, or a test is still running, and the server refuses a second one rather than silently replacing it | — | If you meant to replace it: back on the Broker step press Disconnect (), then paste the new pair. If a test is still running, give it a minute |
Try again and Try again later re-run the 's read-only probe on the pair that is already sealed and stored (a protected action, so you are asked for your code); they never re-send anything you typed earlier, because the form is emptied the moment a pair is stored. If you cancel the code prompt the card stays and says so; press the button again when ready. I pasted a new pair only clears the card so the form underneath can be tested; the rejected connection is retired when the new pair is stored.
Connected with Connect with Alpaca (sign-in) rather than keys? The same cards apply, except the two key cards: a token Alpaca no longer accepts reads "Alpaca no longer accepts the token from that sign-in" and the remedy is pressing Connect with Alpaca again (or pasting keys instead). A blip, a rate limit or an operator-side problem on a signed-in connection gets the same Try again as a key pair; no need to sign in again.
If the Test step never finishes (two minutes with no verdict means the trading service is down or restarting, not that your keys are wrong), the page offers Continue to the console (the check completes on its own later; reopening Connect your broker puts you back on the Test step) and Start over with a new connection, which retires the stuck one (authenticator code) so you can paste or sign in again.
NoteThere is no "clock skew" card for Alpaca. Alpaca's key authentication is not time-signed, so the trading server's clock cannot make a good key pair fail. If your code is refused at the step-up prompt, that is your phone's clock, and a different .
The account is connected but "not active"
This is not a failed test. Alpaca accepted the keys, so the wizard moves on to Connection works, and the card shows what Alpaca says about the account. A brand-new account is occasionally held for review for a few hours (Alpaca reports it as submitted, onboarding or similar); while it is, Alpaca itself may refuse orders, and a refused order shows up as a rejected order with Alpaca's reason, never as a connection problem. Finish anything Alpaca emailed you about; there is nothing to redo in Bellwether, and the note disappears once Alpaca reports the account active.
Keys that worked yesterday
When Alpaca starts refusing a pair that used to work (almost always because new keys were generated in the Alpaca dashboard, which retires the old pair at once), the Executor halts the book (broker_auth_error, a critical alert on Activity › Alerts) and parks the connection. Connect your broker then opens with "Your previous connection stopped working" on the Broker step, a Paste new keys button straight to the paste card, and the Alpaca did not accept this key pair card already showing there; paste the new pair and Test connection replaces the parked one. If the connection was parked by a blip rather than a refusal (the line says it could not reach Alpaca just now and there is nothing to re-paste), the button reads Test it again and the card's Try again re-tests the stored pair. Then press Resume in the banner (Risk › Halts) with your code. The longer story, including outages and the circuit breaker, is on broker disconnected.
For the operator
The Error details line is the connection's recorded last error, verbatim: the exception class and message the Executor's probe raised (for example AuthError: alpaca rejected the API key (GET /v2/account): …, Transient: …, RateLimited: …), or the API's own refusal (invalid: …, the 409 "already has a … connection"). "no Alpaca error code: egress proxy / allowlist?" on a 403 means the request never reached Alpaca's API proper; check the trading server's egress path. "no SESSION_SECRET" / "sealed credentials could not be opened" means the Executor and the API do not share the sealing key. The same string is in the Executor log as connection … failed verification: … (the probe) or book … could not be opened: … (which also raises an ops alert the platform owner sees on Admin).