Error Codes
This page documents the error codes you may encounter when using TestMax. These codes appear in API responses, the output log during backtests, and occasionally in the UI when an operation fails.
TopStep Simulator API error codes
The TopStep Simulator API (/api/topstep-sim/) returns errors as {"success": false, "errorCode": N, "errorMessage": "..."} — with HTTP status 200 (rate limiting is the exception: a real HTTP 429). The codes are contextual — the same number can mean different things on different endpoints — so always read errorMessage:
| Code | Used for | Typical messages | Resolution |
|---|---|---|---|
| 0 | Success | — | No action needed |
| 1 | Missing resources | "Account not found", "Contract not found", "Instrument not found"; on Auth/validate: "Invalid session" | Check the accountId/contractId you sent; re-authenticate if the session is invalid |
| 2 | Invalid state or parameter | "Order not found", "Position not found", "No active replay session", "startDate required", "Unit invalid", "Invalid time range", "Account is not in funded phase"; on Order/place: the engine’s rejection reason (e.g., insufficient margin) | Fix the parameter, or start a replay session first; for order rejections, read the reason |
| 3 | Auth failures and unsupported operations | "Invalid credentials", "Invalid or expired token", "Order modification not supported in simulator", "Invalid payout amount", "Unit number invalid" | Re-authenticate; use cancel + re-place instead of Order/modify |
| 4 | Account/rule violations | "Account violation" (terminal challenge), "Payout not eligible...", "Limit invalid" | A passed/violated/ended challenge cannot keep trading — start a new one; check payout eligibility first |
| 5 | Close/payout failures | "Invalid close size", close-order rejection reasons, "Payout failed — please retry" | Check the close size against your position; retry payouts |
| 6 | Partial-close rejections | The engine’s rejection reason | Read the reason and adjust |
| 7 | Order/session validation | "Invalid order size", "Invalid order type or side", "Failed to start replay" | Size must be an integer from 1–1000; check enum values; check the replay date has data |
| 9 | Pro required | "Pro subscription required for TopStep Simulator API" | Upgrade to Pro from Plans & Pricing |
| 99 | Internal error | "Internal server error" | Retry after a brief wait. If persistent, contact support |
| 429 | Rate limited | "Too many requests" — arrives as a real HTTP 429 with a Retry-After header | Wait the indicated seconds. Limits: login 10/15 min per IP and 5/15 min per email; History/retrieveBars 20/min per account |
Playground API — HTTP status codes
The Playground API (/api/playground/) does not use the errorCode envelope. Errors are real HTTP statuses with a JSON body of {"error": "message"}:
| Status | Meaning | Common scenarios |
|---|---|---|
| 200 | OK | Request succeeded |
| 400 | Bad Request | Empty strategy code, script over 200 KB, missing instrument/startDate, invalid or too-large date range (max 2 years), strategy limit reached (100) |
| 401 | Unauthorized | Not logged in — session cookie is missing or expired |
| 403 | Forbidden | Algo Playground requires a Pro subscription |
| 404 | Not Found | Unknown strategy ID or execution ID (or one owned by another user) |
| 429 | Too Many Requests | You already have a backtest running, the server is at its concurrent-run capacity, or you exceeded 100 requests/min on CRUD endpoints — the Retry-After header says how long to wait |
| 500 | Internal Server Error | An unexpected server error occurred. Retry after a brief wait |
| 502 | Bad Gateway | The server is temporarily unavailable, often during deployments |
| 503 | Service Unavailable | Playground temporarily unavailable, maintenance, or high load |
| 504 | Gateway Timeout | The request took too long to process. Reduce the scope (e.g., smaller date range) and retry |
Common error patterns
Error during backtest execution
If you see errors in the output log during a backtest, they typically follow this format:
[ERROR] API Order/place: 400 Invalid sizeThe format is: [ERROR] API {endpoint}: {HTTP status} {error message}
Common backtest errors:
| Error message | Cause | Fix |
|---|---|---|
Invalid order size | Order quantity is missing, 0, negative, non-integer, or over 1000 | Check your strategy logic for position sizing |
Invalid order type or side | Unknown type or side enum value | Use type 1–4 and side 0–1 — see Enums & Types |
Already running a backtest. Stop it first. | A previous execution is still active (HTTP 429) | Stop it via the UI or /stop, or wait for it to finish |
| Backtest stops after 30 minutes | Execution exceeded the 30-minute timeout | Reduce date range or increase timeframe |
Script too large | Strategy code exceeds 200 KB | Reduce script size — see Common Issues |
Authentication errors after session expiry
If you receive error code 3 (Invalid credentials) or HTTP 401 unexpectedly during normal use, your session token has likely expired. This happens if:
- You have been inactive for an extended period
- Your subscription status changed
- You logged in from another device
Solution: Refresh the page or log out and log back in. Your trading data and settings are preserved.
Concurrent execution errors
An HTTP 429 with the “Already running a backtest” message indicates you are trying to start a second concurrent execution. TestMax enforces a limit of one active backtest per user (and a server-wide cap across all users).
Solution: Stop the existing execution first, or wait for it to complete. If you believe no execution is running, wait a moment for the stale-process auto-cleanup, then try again.
Reporting errors
If you encounter an error that is not documented here or that persists after following the recommended resolution:
- Note the exact error message and error code
- Record the date, time, instrument, and timeframe you were using
- Copy any relevant output log content
- Contact support via the in-app help button or email
Pro subscribers receive priority support response times.