Errors and troubleshooting

The guard that never fires

This is the most common bug we see in a first integration, and it fails silently in the worst possible place: the code path that handles a rejected order.

# BROKEN. r.get("ok") is None on an error, and None is not False,# so this branch never runs and every rejection returns normally.if r.get("ok") is False:    raise RuntimeError(r["error"])

The mirror-image bug is if not r.get("ok") on live, which treats every live success as a failure, because a live success has no ok. Check the HTTP status, or test for the presence of error, which works in both environments:

if not response.ok:                       # requests: any 4xx/5xx    raise RuntimeError(data.get("error"), data.get("message"))if "error" in data:                       # belt and braces    raise RuntimeError(data["error"])

The same trap has a second form: if the body does not parse as JSON at all, you are not talking to the API. A proxy, a captive portal, or an edge security challenge answered instead. Treat a JSONDecodeError as a transport failure and surface it, rather than letting it surface later as a KeyError with no error text. The reusable client handles both.

A wrong key gives invalid_api_key, not wrong_environment

wrong_environment sounds like the error you get for using the wrong kind of key, and it is not. You will almost certainly never see it while integrating.

Authentication resolves the key before it compares environments: it hashes what you sent and looks it up, and an unknown hash is rejected as 401 invalid_api_key without ever reaching the environment check. That ordering is deliberate: it means the API never reveals whether a given key exists. So a key you mistyped, invented, or copied wrong returns 401 invalid_api_key whatever its prefix says:

curl https://api.perpsfund.com/v1/sandbox/account \  -H "X-API-Key: pk_live_000000000000000000000000"# → 401 { "error": "invalid_api_key", "message": "That API key is not valid." }     ← not 403 wrong_environment

403 wrong_environment happens only when the key is real and yours and on the other environment's route: a pk_live_ key on /sandbox/*, or a pk_test_ key on a live route. If you are seeing 401, the problem is the key itself, not which environment it belongs to.

bad_symbol on a real ticker

{ "error": "bad_symbol" } almost always means the symbol is not in the tradeable universe, or it is decorated. Send the plain symbol as /sandbox/markets lists it (for example BTC), not a prefixed or suffixed form. When in doubt, read /sandbox/markets and use a symbol from that list verbatim.

A doubled position after a timeout

On live, send an Idempotency-Key header on every write and resend a timed-out request with the same key: the first response comes back and nothing is placed twice (see Live trading). The sandbox does not deduplicate, so a retried POST /sandbox/orders can open a second position there. If a sandbox write times out, call /sandbox/positions first and only resend if the position is not there.

This is a different problem from concurrent_request, which is the sandbox telling you it declined to run a write rather than run it twice. A concurrent_request is safe to retry; a timeout is not.