PhoenixPerpetualsDocs API v1
Get an API key

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.

View as Markdown

On this page
  1. The families
  2. Retrying safely

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#

typeStatusWhat it meansWhat to do
invalid_request400The call itself is wrong: a missing field, a size off the step, an unknown parameterFix the call; details lists every problem
authentication401No key, or one that is wrong, expired, revoked, or for the other environmentDo not retry; check the key and the host
permission403The key may not do this: read-only, outside its IP allowlist, or access is offDo not retry; change the key in the dashboard
not_found404No such account, order, market or route for this keyCheck the id; an account outside your key's reach is also not found
method405The path exists with another method (Allow lists them)Use the right method
conflict409The state changed: the order is no longer working, the exits movedRead the state again, then decide
payload413, 414, 415The body is too large (413), the address too long (414), or not JSON (415)Send less, or JSON
rule_rejection422The account's rules or the market said no: margin, a loss limit, a closed marketChange the order; retrying the same one fails the same way
key_limit422Your key's own limits said no: its markets, its largest order, its daily loss stopChange the order, or the key's limits
rate_limit429Too many callsWait Retry-After seconds (see Rate limits)
server500, 503Something 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
engine503The trading servers are busy or out of reach for a momentRetry 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.

Guides, endpoints, fields and error codes.