API reference · testnet
Errors
What each status code and error message means, and what to do about it.
HTTP status codes
| Code | Meaning |
|---|
| 200 | Answered. For /exchange, check status: the action itself may have failed in its block |
| 400 | Bad request, or refused before it reached a block (reason in the body) |
| 403 | Refused by Cloudflare (for example a request that sets CF-Connecting-IP) |
| 404 | Unknown endpoint |
| 405 | Wrong method (/info, /exchange and /faucet are POST) |
| 426 | /ws without a WebSocket upgrade |
| 429 | Rate limited: wait Retry-After seconds (Rules) |
Refused before a block
400, {"status": "err", "response": "<message>"}. Nothing happened and the nonce was not used.
| Message | Notes |
|---|
bad request: … | The body isn't a valid request (missing field, wrong type, unknown action type) |
signature is not hex | |
signatureChainId is required for wallet-signed actions | See Signing |
bad signature: Malformed | BadRecoveryId | NonCanonical | Unrecoverable | Not 65 bytes; v not 0, 1, 27 or 28; high-s (EIP-2); or no key recovers |
signer is neither the account nor its approved agent | Wrong key, wrong chain id, or a field differs from what was signed |
protocol accounts cannot be used | |
this node has no spot market | |
cannot send to a protocol account | spotSend |
invalid agent | approveAgent: the agent is the signer itself or a protocol account |
address rate limit: … next request allowed in … ms | See Rules: address limits |
nonce outside (now − 2 days, now + 1 day) | See Rules: nonces |
nonce already used | Safe to treat as a duplicate of an accepted request |
nonce below the signer's window | See Rules: nonces |
tif must be Gtc, Ioc or Alo | |
unknown vault | vaultTransfer |
user must be a 0x address | /faucet |
invalid address | /faucet: a protocol account or the zero address |
faucet already used; try again in … min | /faucet: once per address per 24 hours |
Failed in a block
200, status: "err", result.ok: false, and result.error holds the chain's error, nested as Outer(Inner), for example Ch(InsufficientMargin), Spot(CancelFrozen), Vault(Locked { until_ms: 1791754154108 }) or TooManyOpenOrders { open: 1000, limit: 1000 }. The nonce was used.
TxError
| Variant | Meaning |
|---|
NotValidator | Validator-only action |
StaleOracle | The market's oracle price is stale: only reduce-only orders until it is fresh |
NoSpotMarket | This node has no spot market |
WithdrawalsPaused | Some account has negative equity: withdrawals and perpetuals → spot transfers wait until it is settled |
TooManyOpenOrders | TooManyOpenOrders { open, limit }: the account is at its open-order limit (see Rules) |
Ch | Perpetuals error, below |
Oracle | Oracle error (validators only) |
Spot | Spot error, below |
Vault | Vault error, below |
ChError
| Variant | Meaning |
|---|
UnknownMarket | No such market |
NoMarkPrice | The market has no mark price yet |
InsufficientMargin | Not enough margin for the order or the leverage change |
InsufficientBalance | Not enough withdrawable USDC |
ReduceOnlyWouldIncrease | A reduce-only order would increase the position |
ZeroAmount | Amount is zero |
ProtocolAccount | Protocol accounts can't do this |
NotLiquidatable | The account is not liquidatable |
OrderTooLarge | Order notional above the market maximum |
PriceTooFarFromOracle | Limit price more than 20% from the oracle |
TooAggressiveAtOiCap | At the open-interest cap, orders priced through the oracle are refused |
OpenInterestCap | The order would take open interest above the cap |
OpenInterestIncreaseTooFast | Open interest is growing too fast this block |
NoOraclePrice | No oracle price yet |
FundingNotDue | Internal: funding is settled once an hour |
TimeWentBackwards | Internal: an older price update |
OrderTooSmall | Order notional below $10 (reduce-only orders are exempt) |
InvalidLeverage | Leverage 0 or above the market maximum |
ExceedsMarginTier | The position would exceed its margin tier at this leverage |
Book | Order book error, below |
Math | Arithmetic overflow (report it) |
LaunchError
| Variant | Meaning |
|---|
TooSmall | Below the minimum order (1 FCTR) |
ZeroPrice | Price is zero |
TifNotAllowedInPhase | Auctions take GTC orders only |
CancelFrozen | Cancels are frozen in the opening auction's closing window |
PriceOutsideBand | Continuous trading: limit too far from the last price |
InsufficientUsdc | Not enough spot USDC to fund the bid |
UnknownOrder | No such order |
NotOwner | The order belongs to another account |
ReservedAccount | Protocol accounts and the clearing pool can't trade or receive |
Token | FCTR ledger error (for example sending locked FCTR) |
Book | Order book error, below |
Math | Arithmetic overflow (report it) |
VaultError
| Variant | Meaning |
|---|
UnknownVault | No such vault |
ZeroAmount | Amount is zero |
TooSmall | Deposit worth less than one share |
Insolvent | Vault equity ≤ 0: no deposits or withdrawals |
Locked | Locked { until_ms }: inside the 4-day lock-up |
NoShares | The account holds no shares |
Illiquid | The vault can't free enough margin for this withdrawal; nothing happened |
NotAllowed | Vaults and protocol accounts can't deposit into a vault |
Ch | Perpetuals error, above |
Math | Arithmetic overflow (report it) |
BookError
| Variant | Meaning |
|---|
ZeroSize | Size is zero |
ZeroPrice | Price is zero |
AloWouldCross | A post-only (ALO) order would have traded on arrival |
DuplicateId | Internal: duplicate order id |
UnknownOrder | No such order |
NotOwner | The order belongs to another account |
Math | Arithmetic overflow (report it) |