Sandbox vs. Live Broker APIs
Direct Answer
Broker sandbox environments test your code's ability to form correct API messages and handle the response schemas your broker uses. They do not test how your strategy behaves under realistic execution conditions. Sandbox fill simulation is almost universally optimistic: orders fill immediately at the exact price requested, with no slippage, no partial fills on large orders, no queue position effects, and no market impact. The trading calendar may or may not be enforced. Rate limits may be more lenient. Margin calculations may use simplified rules or return static mock values.
When you move from sandbox to live, you will encounter partial fills on large orders at thin prices, market orders that fill at prices meaningfully different from the last quote, GTC orders that persist correctly but accumulate overnight as expected, rate limits that enforce more strictly at market open than at midday, and occasionally broker behaviors that have no equivalent in the sandbox at all, such as margin calls, exchange-level halts on individual symbols, or authentication token edge cases that only surface under live session conditions.
Key Takeaways
- Sandbox validates message format, not execution behavior: A passing sandbox test means your code can form the right JSON and parse the response. It does not mean your execution logic handles real-market conditions correctly.
- Fill simulation is always optimistic: Sandbox fills are typically instant and complete. Live fills can be partial, delayed, or at different prices than your limit. Your position tracking must handle all these cases.
- Rate limits may differ: Sandbox rate limits are sometimes more lenient than live. A system that works cleanly at 100 requests/minute in sandbox may hit the live limit at 80 requests/minute during a high-activity period.
- Margin behavior often diverges: Sandbox buying power calculations may use simplified margin rules, ignoring maintenance margin, house requirements, and PDT restrictions. In live, these rules can cause unexpected order rejections.
- Live environments have unique error codes: Some broker error codes, halt-triggered rejections, margin call notifications, duplicate order detection, only appear in live environments. Design your error handling to cope with unknown error codes gracefully.
- Authentication token edge cases appear in live: OAuth token expiry under load, concurrent session conflicts, and IP restriction enforcement are all more likely to surface in live than in the low-usage sandbox environment.
- WebSocket behavior may differ: Sandbox WebSocket feeds sometimes deliver events with different timing or completeness than live feeds. A live fill event may include additional fields (execution venue, liquidity flag) not present in sandbox fill events.
- Start live with small size: The first live deployment should use the smallest possible order sizes, often 1 share or minimum order value, to validate end-to-end live behavior before scaling up. Treat the first week of live trading as a final integration test.
Core Concepts
Fill Simulation: Sandbox Optimism vs. Live Reality
Most broker sandbox environments simulate fills by immediately matching any submitted order against the current market price, regardless of the order's price relative to the market. A limit buy at $100 submitted when the market is at $102 fills immediately at $100 in the sandbox because the simulator is just checking "does the limit price overlap with the current price?" and answering "yes" for any in-the-money limit. In live, the same order would sit in the book unfilled until the price declines to $100.
Partial fills, where a large order fills in multiple chunks as liquidity becomes available, are essentially never simulated in sandbox environments. A market order for 10,000 shares in the sandbox fills 10,000 immediately. In live, a 10,000-share order in a stock with average daily volume of 100,000 shares may fill in 3-5 chunks over 30-60 seconds, each at a slightly different price. Your position tracking and P&L calculation must handle a sequence of partial fills summing to the total quantity, not a single complete fill.
Market impact, the price movement caused by your own order, is not simulated in sandbox. For a small retail-scale account, market impact on liquid equities is negligible. For accounts trading significant fractions of daily volume, or for illiquid securities, market impact is a real cost that sandbox testing will never reveal. Build your live position sizing to use a lower fraction of average daily volume than your sandbox testing suggested, at least until you have live execution data to calibrate against.
Slippage on market orders is another sandbox omission. A sandbox market order for 500 shares of AAPL fills at the last-quoted price. A live market order for 500 shares may walk up the order book by $0.01-$0.05 depending on the current bid/ask spread and available depth. For strategies with tight P&L requirements (scalping, mean reversion with small expected returns), this slippage matters significantly and must be accounted for in live deployment.
Rate Limit Differences Between Sandbox and Live
Broker sandbox environments are shared infrastructure used by developers testing their integrations. They typically impose rate limits to prevent abuse, but these limits may be set differently from the live environment. Alpaca's paper trading environment uses the same rate limits as live as of their current documentation, but other brokers may use higher (more lenient) limits in sandbox, lower limits, or no limits at all.
The live environment also has rate-limit behavior that varies by time of day and market conditions. Rate limits at 09:30 ET market open, when every algorithmic trader simultaneously submits opening-moment orders, may behave differently than at midday. Some brokers implement adaptive rate limiting that tightens limits during peak load periods. A system that performs within limits at 11:00 ET sandbox may hit rate limits at 09:30 ET live.
Test rate limit behavior in live using a small initial deployment window: start trading 30 minutes after the open, not at the open itself. Monitor 429 response rates in live versus sandbox. If you see 429s in live that didn't appear in sandbox, your rate limiter needs to be more conservative. Reduce your proactive rate limit to 70% of the live-observed limit rather than 90% of the documented limit, to give more buffer for peak-load variability.
Some brokers also enforce IP-level rate limits in addition to API-key-level limits. If multiple instances of your system are running simultaneously (dev instance, staging instance, production instance), they may all share the same IP-level budget even if they use different API keys. Live deployments with multiple processes should use a shared rate limiter across all processes, not independent per-process rate limiters that each assume they have the full limit available.
Margin and Account State Divergence
Sandbox account state is often initialized to a fixed amount (Alpaca paper accounts start with $100,000) and uses simplified buying power calculations. Maintenance margin requirements, house margin requirements, and PDT restrictions may not be enforced in sandbox. An order that succeeds in sandbox against a $100,000 paper account may fail in live against a real $50,000 margin account where house margin requirements reduce the effective buying power further than the basic Reg-T calculation would suggest.
Sandbox margin accounts also don't receive margin calls. In live, if your leveraged positions decline enough to breach the maintenance margin threshold. The broker will issue a margin call requiring additional equity or position liquidation within a short timeframe (often the same day). A system not designed to handle margin calls, which may arrive as a specific status flag in the account object, will fail silently while the broker begins forced liquidation of positions.
PDT restrictions in live can activate mid-day: if your account equity drops below $25,000 during trading and you've made 3 day trades in the rolling 5-day window, subsequent intraday trades may be rejected as PDT rule violations. Sandbox environments do not simulate equity-based PDT restriction activation. Build PDT detection into your live trading logic by monitoring the account's PDT status field and day-trade count field, and alerting when approaching the limit.
The fix: before going live, create a detailed account-state comparison document. Side by side: your sandbox account's buying power, margin type, PDT status, and day-trade count versus your live account's equivalent fields. Run the same order through both environments and compare the accepted quantities, buying power deductions, and fill responses. Any discrepancy identifies a live-specific behavior you need to handle.
Production-Only Error States and Edge Cases
Some broker error codes and behaviors appear exclusively in live environments because they require real market conditions, real position state, or real regulatory enforcement to trigger. The most common production-only errors: exchange halt rejections (symbol is halted for a news event), short-locate failures (your broker can't borrow the shares for a short sell), margin call notifications (account equity insufficient for current positions), settlement failures (counterparty failed to deliver on a purchased position), and authentication token conflicts from concurrent API sessions exceeding the broker's per-user session limit.
Short-locate failures deserve special attention for systems that short sell. When you attempt to sell short, your broker must first confirm it has shares available to borrow ("locate" the shares). In liquid large-cap stocks, locates are almost always available. In small-cap, micro-cap, or heavily-shorted stocks. The broker may be unable to locate shares, returning a specific error indicating the short order cannot be filled. This rejection only occurs in live; sandbox doesn't simulate borrow availability at all. Your adapter must handle short-locate failures specifically, they are not retriable (the shares aren't available, retrying doesn't change that) and require the strategy to abandon the short intent or route to a different broker with available borrow.
Authentication edge cases also surface in live: a browser-based OAuth flow may generate a token that works in sandbox but fails in live if the live environment uses a different OAuth scope validation. Concurrent sessions, your system running in two tabs or two processes simultaneously with the same API key, may work in sandbox but trigger session conflict errors in live. Test authentication explicitly against the live environment during your initial deployment.
Design your error handler to log all unrecognized error codes to a high-priority alert channel. In the first week of live deployment, you should expect to see at least a few error codes not present in your sandbox testing. Each one requires investigation and a specific handler addition. An unrecognized error code treated as a generic transient error may incorrectly retry an order that should never be retried (like a short-locate failure).
Worked Scenario
- Sandbox test. Your strategy submits a limit buy for 2000 shares of MRNA at $95.50. The current ask is $95.65. Sandbox fills the order immediately at $95.50. Your system logs: "filled 2000 @ $95.50".
- Live deployment, same order. MRNA's average daily volume is 4 million shares. Your 2000 share order is 0.05% of ADV, small enough that market impact is minimal. The limit sits in the book at $95.50.
- Live partial fill. After 3 minutes, 800 shares fill at $95.50. After another 2 minutes, 1200 shares fill at $95.50 as the price dips. Total: 2000 shares in two fills.
- System state after first partial. Internal position = 800 shares, not 2000. The GTC order is still working for the remaining 1200. A second strategy evaluation fires and sees a 800-share position when it expected 2000, it tries to submit another buy for 1200 shares to reach the target. This creates 2400 shares of open buy orders when only 1200 is needed.
- Root cause. The position tracking assumes fills are complete (sandbox always fills completely). In live, it needs to track partial fills and check whether an order for the remainder is already working before submitting another.
- Fix. Add logic: before submitting a fill-gap order, check if there's already an open order for this symbol and side. If the total of (existing position + open buy order quantity) equals the target. Don't submit another buy. Only submit if there's a genuine shortfall not covered by working orders.
Measurement Framework
| Measurement | Question to Answer |
|---|---|
| Partial fill rate (live vs. sandbox) | What fraction of orders result in partial fills in live that would have been full fills in sandbox? |
| Slippage per order (market orders) | What is the average difference between the last-quoted price at submission time and the actual fill price? |
| Production-only error code frequency | How many unique error codes have been observed in live that weren't encountered in sandbox testing? |
| Time-to-fill (p50/p95) live vs. sandbox | How much longer do orders take to fill in live versus sandbox, and how does this affect strategy timing assumptions? |
| Authentication failure rate in live | How often do authentication errors occur in live that were absent from sandbox testing? |
Common Failure Modes
Strategy Logic Assumes Instant Full Fill
A strategy written against the sandbox assumption that orders fill immediately and completely will fail in live when a partial fill leaves the strategy in a partially-executed state for minutes or longer. Strategy evaluation logic that fires based on position size will see an incorrect position, potentially triggering duplicate orders or wrong-direction signals.
Decouple strategy evaluation from fill timing. After submitting an order, the strategy should track the pending order separately from confirmed position until the fill event is received. Strategy re-evaluation should be aware of pending orders and include their expected quantity in position projections, not assume they've already filled.
Margin Rules Not Enforced in Sandbox
A system that sizes orders using sandbox buying power (a simplified $100k paper account) and then goes live against a real account with stricter house margin requirements will immediately hit order rejections. The live account's effective buying power is lower than the sandbox account's simplified calculation suggested, and orders sized for sandbox will be over-limit in live.
Before going live, explicitly query the live account's current buying power, equity, and margin status using the live (not sandbox) API endpoint with the live API key. Use these real values to calibrate your order sizing, not sandbox values extrapolated to a different account size.
Unhandled Short-Locate Failure
A strategy that short-sells without handling borrow-unavailability errors will encounter an unexpected error code on its first short attempt in a stock where borrow is scarce. If the error handler treats it as a generic retryable error, the system retries repeatedly, all failing, while the strategy believes its short order is pending. The position state is wrong, the retry loop consumes rate-limit budget, and no short position was established.
Add explicit handling for short-locate failure error codes (obtain these from your broker's error code documentation or through sandbox testing against deliberately illiquid test symbols). When a short-locate failure is detected, surface it immediately as a non-retryable error with a clear message. Let the strategy decide whether to attempt a different broker with available borrow or abandon the short intent.
WebSocket Events in Live Contain Unexpected Fields
Live execution reports often include additional fields not present in sandbox test responses: exchange execution venue (EDGX, ARCA, BATS, etc.), liquidity indicator (added/removed/unknown), FINRA trade reporting flag, and extended regulatory information. A JSON parser that fails on unexpected fields, rather than ignoring them, will crash when processing live fill events.
Use permissive parsing: extract the fields your system needs and ignore all others. Never assume you know all the fields a broker might send in the future. Log the full raw event for debugging, but parse only the fields you explicitly need.
FAQ
How long should I test in sandbox before going live?
There is no minimum sandbox duration that guarantees live readiness, the sandbox does not simulate live behavior well enough to be a proxy for a time-based confidence threshold. Instead, define a readiness checklist: all contract tests pass, all error handling paths have been tested, the system has been running continuously for 48 hours without crashing, and a human has reviewed the order lifecycle from signal to fill in a real sandbox session. Once the checklist is complete, proceed to live with minimum order sizes regardless of elapsed sandbox time. More sandbox time is not a substitute for a structured readiness assessment.
Should I run sandbox and live in parallel for ongoing regression testing?
Yes, with important caveats. Running the same strategy logic against sandbox alongside live allows you to detect divergences in broker response behavior that might indicate an API change. But never use sandbox P&L as a proxy for live P&L evaluation, sandbox fills will be better than live fills almost universally, creating a false impression of strategy performance. Use sandbox in parallel only for API regression testing (do messages still parse correctly?) not for strategy performance evaluation.
What is the safest way to transition from sandbox to live?
Four-stage approach: (1) Complete sandbox testing and readiness checklist. (2) Go live with the smallest possible order sizes, $100 notional, 1 share, minimum contract value, for a full week of market sessions. Monitor every order, every fill, and every error code. (3) After a clean week, double the order size and monitor for a second week. (4) Scale to target size only after two weeks of clean live operation at reduced size. Any unexpected error or behavior discovered at any stage is a stop: investigate before continuing to scale.
Can I use the live API with very small orders as an extended sandbox?
Yes, and this is called "paper trading with real money", small-size live testing. It exposes you to all the live API behaviors sandbox doesn't simulate (real fills, real margin calculations, real authentication edge cases) at minimal financial risk. The per-share or per-trade risk on 1 share of a $10 stock is small enough to be treated as an integration test cost. Many production trading systems use this approach when moving to a new broker or when testing a new strategy component.
Which bugs commonly appear only in live and not in sandbox?
The most frequent live-only bugs: (1) partial-fill handling, position tracking assumes complete fills; (2) authentication token expiry under session-hours duration, sandbox sessions are short; (3) margin call event handling, sandbox doesn't issue margin calls; (4) short-locate failure handling, sandbox always grants locates; (5) WebSocket event field differences, live events often have extra fields not in sandbox; (6) rate limiting under market-open load, sandbox doesn't replicate the concurrent load of real market hours; (7) exchange halt rejection handling, requires real market microstructure events to trigger.
Do sandbox environments use real market data?
It varies, and the answer changes what sandbox results mean. Some replay delayed real data, some generate synthetic prices, and some use a static fixture set that never moves. A strategy tested against synthetic or static prices has been tested against the data generator rather than against the market, so its signal behavior tells you nothing. Establishing which of these applies before drawing conclusions from a sandbox run is more informative than the run itself.
How do sandbox rate limits typically differ from production?
Sandboxes are often more permissive, sometimes with no enforcement at all, because they carry less load and are meant for development. A client that never encountered a limit in testing therefore has completely untested throttling and backoff paths on its first live day. Where the sandbox does enforce limits, the thresholds may differ from production in either direction. Testing the backoff path deliberately, by lowering the client own limit until it triggers, exercises the code without depending on the environment to do it.
What happens to sandbox accounts between sessions, and why does that hide bugs?
Many sandboxes reset balances, clear positions, and cancel open orders on a schedule or on request. That produces a clean starting state every run, which conveniently hides any bug involving state carried across sessions: stale open orders, positions that survived a restart, or reconciliation logic that has never seen a non-empty starting position. Deliberately running a session that begins with existing positions and resting orders tests the path that a reset environment never reaches.
Should sandbox and live run through the same code path?
Yes, with the environment differing only in configuration such as the endpoint and credentials. A separate code branch for sandbox means the live path is exercised for the first time in production, which removes most of the value of testing. Where behavior genuinely has to differ, isolating it behind a single well-named flag keeps the difference visible and reviewable, rather than spreading environment checks through the codebase where they are easy to lose track of.
References
- Alpaca Markets: Paper Trading Documentation: Official documentation on how Alpaca's paper trading environment differs from live, including fill simulation behavior.
- FINRA Rule 4210: Margin Requirements: Regulatory basis for margin behaviors that differ between simplified sandbox calculations and live enforcement.
- SEC: Key Points About Regulation SHO: Explains locate requirements for short selling that cause production-only failures in systems that haven't handled borrow unavailability.
- FINRA: Pattern Day Trading Rules: PDT rules that create live-environment-only account restrictions not simulated in sandbox.
Educational Disclaimer
This guide is for educational and informational purposes only. It does not constitute financial, investment, or legal advice. Live trading involves real financial risk, including the loss of your entire capital. Always start with the smallest viable position sizes when transitioning from sandbox to live and ensure proper risk controls are in place before scaling.