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.
Simulator API error codes
The Simulator API (/api/sim/) returns errors as {"success": false, "errorCode": N, "errorMessage": "..."} — with HTTP status 200 (two exceptions: rate limiting and exhausted allowances are a real HTTP 429, and a replay session that is busy or loading its next data window answers a real HTTP 503 with Retry-After: 1 — retry both after the header’s seconds). 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", "Invalid endDate", "endDate must be after startDate", "Date range too large (max 2 years)", "Unit invalid", "Invalid time range", "Invalid timeframe for this instrument", "Account is not in the performance phase"; on Order/place: the engine’s rejection reason (e.g., insufficient margin) | Fix the parameter, or start a replay session first; for "Invalid timeframe for this instrument", request a bar width the contract’s stored data can build (a whole multiple of its stored bar width); 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 withdrawal amount", "Unit number invalid" | Re-authenticate; use cancel + re-place instead of Order/modify |
| 4 | Account/rule violations | "Account violation" (terminal challenge), "Withdrawal not eligible...", "Limit invalid"; on Replay/start: "Too many active replay sessions (max 10) — end one with Replay/end first" | A passed/violated/ended challenge cannot keep trading — start a new one; check withdrawal eligibility first; call Replay/end on a session you have finished with instead of abandoning it |
| 5 | Close/withdrawal failures | "Invalid close size", close-order rejection reasons, "Withdrawal failed — please retry" | Check the close size against your position; retry the withdrawal |
| 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 | Plan required | "Pro subscription required for the Simulator API"; on History/retrieveBars and Replay/start, also "Requires the <plan> plan" when the contract is not part of your plan | Upgrade from Plans & Pricing; the second form means that specific contract is not included in your plan, not that your subscription lapsed |
| 99 | Internal error | "Internal server error" | Retry after a brief wait. If persistent, contact support |
| 429 | Rate limited or out of daily data | "Too many requests" — arrives as a real HTTP 429 with a Retry-After header; on History/retrieveBars, also "Daily data limit reached. Resets at 00:00 UTC." once the account’s daily bar budget is spent | Wait the indicated seconds — for the daily budget Retry-After counts down to 00:00 UTC and can be hours, so back off rather than retrying in a loop. Limits: login 10/15 min per IP and 5/15 min per email; History/retrieveBars 20/min per account and Replay/start 20/min per account, plus the daily bar budget |
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, or "<SYMBOL> requires the <plan> plan" when the instrument you asked to backtest is not part of your plan |
| 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.