Working with the API
Errors.
One error shape for every call: what the type, the code and retryable tell your code, and what to do about each family.
On this page
Every error has the same shape, whatever the call:
{
"error": {
"type": "rule_rejection",
"code": "insufficient_margin",
"message": "Not enough margin for this order.",
"request_id": "req_0f9c2a7d8e1b4c6a9f3e5d7b1a2c4e6f",
"retryable": false,
"doc_url": "https://docs.phoenixperpsfunding.com/reference/errors#insufficient_margin",
"details": { "required_usd": "1250", "available_usd": "830" }
}
}- **
code** is the contract: match on it in your code. Codes never change meaning, and every one is explained in the error reference. - **
type** is the family the code belongs to, and decides the HTTP status. - **
message** is for people. Show it or log it, never match on it: it may be reworded. - **
retryable** says whether the same call may work if you send it again later. - **
details**, when there is something to add: the fields at fault, the limits involved, the nearest valid sizes. - An error about an order also names it in
order_id.
The families#
type | Status | What it means | What to do |
|---|---|---|---|
invalid_request | 400 | The call itself is wrong: a missing field, a size off the step, an unknown parameter | Fix the call; details lists every problem |
authentication | 401 | No key, or one that is wrong, expired, revoked, or for the other environment | Do not retry; check the key and the host |
permission | 403 | The key may not do this: read-only, outside its IP allowlist, or access is off | Do not retry; change the key in the dashboard |
not_found | 404 | No such account, order, market or route for this key | Check the id; an account outside your key's reach is also not found |
method | 405 | The path exists with another method (Allow lists them) | Use the right method |
conflict | 409 | The state changed: the order is no longer working, the exits moved | Read the state again, then decide |
payload | 413, 414, 415 | The body is too large (413), the address too long (414), or not JSON (415) | Send less, or JSON |
rule_rejection | 422 | The account's rules or the market said no: margin, a loss limit, a closed market | Change the order; retrying the same one fails the same way |
key_limit | 422 | Your key's own limits said no: its markets, its largest order, its daily loss stop | Change the order, or the key's limits |
rate_limit | 429 | Too many calls | Wait Retry-After seconds (see Rate limits) |
server | 500, 503 | Something went wrong on our side (500), or a part of it is out of reach for a moment (503) | Retry later if retryable; quote the request_id if it lasts |
engine | 503 | The trading servers are busy or out of reach for a moment | Retry after Retry-After, with the same Idempotency-Key |
Retrying safely#
Retry only when retryable is true, after the Retry-After header when there is one, and with a growing pause between tries. For a call that changes something, retry with **the same Idempotency-Key**: if the first try did reach us, you get its result back instead of a second order (see Idempotency).
A refusal by the account's rules is not retryable: sending the same order again gets the same answer. The SDKs retry what is safe to retry by themselves, and raise the rest as typed errors:
import { PhoenixPerps, RuleRejectedError } from "@phoenixperps/sdk";
const client = new PhoenixPerps();
try {
await client.orders.create("SANDBOX-00042-001", { market: "BTC-USD", side: "buy", type: "market", size: "100" });
} catch (err) {
if (err instanceof RuleRejectedError) console.log(err.code, err.details); // insufficient_margin { required_usd, available_usd }
else throw err;
}from phoenixperps import PhoenixPerps, RuleRejectedError
client = PhoenixPerps()
try:
client.orders.create("SANDBOX-00042-001", {"market": "BTC-USD", "side": "buy", "type": "market", "size": "100"})
except RuleRejectedError as err:
print(err.code, err.details) # insufficient_margin {'required_usd': ..., 'available_usd': ...}_, err := client.Orders.Create(ctx, "SANDBOX-00042-001", phoenixperps.CreateOrder{
Market: "BTC-USD", Side: phoenixperps.OrderSideBuy, Type: phoenixperps.CreateOrderTypeMarket, Size: phoenixperps.Dec("100"),
})
var e *phoenixperps.Error
if errors.As(err, &e) && errors.Is(err, phoenixperps.ErrRuleRejected) {
fmt.Println(e.Code, e.Details) // insufficient_margin
}try
{
await client.Orders.CreateAsync("SANDBOX-00042-001", new CreateOrder { Market = "BTC-USD", Side = OrderSide.Buy, Type = CreateOrderType.Market, Size = 100m });
}
catch (RuleRejectedException e)
{
Console.WriteLine($"{e.Code} {e.Details}"); // insufficient_margin
}try {
client.orders().create("SANDBOX-00042-001", new CreateOrder().market("BTC-USD").side(OrderSide.BUY).type(CreateOrderType.MARKET).size(new BigDecimal("100")));
} catch (PhoenixPerpsException.RuleRejectedException e) {
System.out.println(e.code() + " " + e.details()); // insufficient_margin
}let order = CreateOrder { market: "BTC-USD".into(), side: OrderSide::Buy, r#type: CreateOrderType::Market, size: Some(dec("100")), ..Default::default() };
match client.orders().create("SANDBOX-00042-001", &order).await {
Err(e) if e.kind == ErrorKind::RuleRejected => println!("{:?} {:?}", e.code, e.details), // insufficient_margin
other => { other?; }
}try {
$client->orders->create('SANDBOX-00042-001', ['market' => 'BTC-USD', 'side' => 'buy', 'type' => 'market', 'size' => '100']);
} catch (PhoenixPerps\Exception\RuleRejectedException $e) {
echo $e->errorCode, ' ', json_encode($e->details), PHP_EOL; // insufficient_margin
}Before sending an order you are unsure of, [POST .../orders/test](/reference/orders/preview-an-order) answers what it would do, refusal included, without placing anything.