# Errors

One error shape for every call: what the type, the code and retryable tell your code, and what to do about each family.

Every error has the same shape, whatever the call:

```json
{
  "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](/reference/errors).
- **`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](/guides/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](/guides/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:

```typescript
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;
}
```

```python
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': ...}
```

```go
_, 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
}
```

```csharp
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
}
```

```java
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
}
```

```rust
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?; }
}
```

```php
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.
