Error Reference

PMXT’s error hierarchy is designed so the same except/catch clause works in both hosted and self-hosted modes. Hosted errors descend from HostedTradingError and from a semantic parent (InsufficientFunds, InvalidOrder, AuthenticationError, etc.). Self-hosted errors raise the semantic parent directly. Catch the parent and you cover both paths. For recovery patterns and the five most-common errors with code, see Handling hosted errors.

Hierarchy

PmxtError                                    (root for the whole SDK)
├── ValidationError                          (local-only — bad arguments)
│   └── MissingWalletAddress                 (escrow call without wallet_address)
├── AuthenticationError
│   ├── InvalidApiKey                  ◄── hosted
│   └── InvalidSignature               ◄── hosted
├── InsufficientFunds
│   └── InsufficientEscrowBalance      ◄── hosted
├── InvalidOrder
│   ├── OrderSizeTooSmall              ◄── hosted
│   ├── BuiltOrderExpired              ◄── hosted
│   └── NoLiquidity                    ◄── hosted
├── NotFoundError
│   └── OutcomeNotFound                ◄── hosted
├── ExchangeNotAvailable
│   └── CatalogUnavailable             ◄── hosted (retryable)
├── NotSupported
└── HostedTradingError                       (any 4xx/5xx from trade.pmxt.dev)
    │
    └── (all classes marked ◄── hosted above are also HostedTradingError)

In Python this is implemented via multi-inheritance: class InsufficientEscrowBalance(InsufficientFunds, HostedTradingError). In TypeScript, JS single-inheritance means each hosted leaf extends only its semantic parent, and the HostedTradingError membership is carried by a static isHostedError = true flag. Use the isHostedError(e) helper to test for membership.

`HostedTradingError`

Root of all errors returned by trade.pmxt.dev.


Status code	Any 4xx or 5xx from the hosted trading API
Detail body	`{ "error": "..." }` or `{ "detail": "..." }` or `{ "success": false, "error": "..." }`
Parents (Python)	`PmxtError`
TS membership	`e instanceof HostedTradingError` or `isHostedError(e) === true`
Retryable	5xx → yes; 4xx → no (unless a leaf overrides)
Fields	`e.status` (int), `e.detail` (str)

from pmxt._hosted_errors import HostedTradingError

try:
    client.create_order(...)
except HostedTradingError as e:
    print(e.status, e.detail)

`InsufficientEscrowBalance`

Escrow free balance is below the order’s USDC requirement.


Status code	`400`
Detail starts with	`Insufficient escrow balance`
Parents (Python)	`InsufficientFunds`, `HostedTradingError`
TS extends	`InsufficientFunds`; `static isHostedError = true`
Retryable	No (deposit and retry)

Recovery: top up via client.escrow.deposit_tx(...).

`OrderSizeTooSmall`

Resolved share count is below the venue’s minimum (Polymarket: 5 shares).


Status code	`400`
Detail contains	`below the minimum`
Parents (Python)	`InvalidOrder`, `HostedTradingError`
TS extends	`InvalidOrder`; `static isHostedError = true`
Retryable	No (resize and retry)

`InvalidApiKey`

pmxt_api_key is missing, malformed, revoked, or expired.


Status code	`401` (always)
Detail	`invalid api key` or `missing api key`
Parents (Python)	`AuthenticationError`, `HostedTradingError`
TS extends	`AuthenticationError`; `static isHostedError = true`
Retryable	No

Recovery: rotate the key in the dashboard. Do not retry with the same key.

`OutcomeNotFound`

Catalog could not resolve the requested outcome_id (or market_id).


Status code	`404`
Detail contains	`catalog: no outcome`
Parents (Python)	`NotFoundError`, `HostedTradingError`
TS extends	`NotFoundError`; `static isHostedError = true`
Retryable	No

Most often: you passed a venue-native ID to a hosted endpoint that expects a catalog UUID. See Catalog UUID vs venue ID.

`CatalogUnavailable`

The hosted catalog is temporarily unavailable.


Status code	`502` / `503`
Detail starts with	`catalog:`
Parents (Python)	`ExchangeNotAvailable`, `HostedTradingError`
TS extends	`ExchangeNotAvailable`; `static isHostedError = true`
Retryable	Yes (override on `DEFAULT_RETRYABLE`)

Recovery: retry with exponential backoff.

`BuiltOrderExpired`

The built_order_id or cancel_id TTL elapsed before submit/cancel.


Status code	`400`
Detail contains	`built_order_id expired` or `cancel_id expired`
Parents (Python)	`InvalidOrder`, `HostedTradingError`
TS extends	`InvalidOrder`; `static isHostedError = true`
Retryable	No (re-build and re-sign)

Re-call build_order, re-sign, re-submit. Common cause: slow hardware-wallet confirmations.

`InvalidSignature`

The hosted trading API rejected the EIP-712 signature or typed-data shape.


Status code	`400` / `401`
Detail contains	`Invalid signature`
Parents (Python)	`AuthenticationError`, `HostedTradingError`
TS extends	`AuthenticationError`; `static isHostedError = true`
Retryable	No

Most often: signing the wrong domain (chain ID, verifying contract). See Signing.

`NoLiquidity`

Empty book on the side you’re crossing.


Status code	`400`
Detail contains	`book has no resting asks` or `book has no resting bids`
Parents (Python)	`InvalidOrder`, `HostedTradingError`
TS extends	`InvalidOrder`; `static isHostedError = true`
Retryable	No (post a limit instead, or wait)

`MissingWalletAddress`

Local validation — client.escrow.* was called without a wallet_address.


Status code	n/a (local)
Parents (Python)	`ValidationError`
TS extends	`ValidationError`
Hosted member?	No — this is a local pre-flight check, not a hosted-API response

Pass wallet_address to the exchange constructor.

Catching by intent

Intent	Catch (Python)	Catch (TypeScript)
Any hosted error	`except HostedTradingError`	`if (isHostedError(e))`
Any auth problem	`except AuthenticationError`	`e instanceof AuthenticationError`
Any insufficient-funds	`except InsufficientFunds`	`e instanceof InsufficientFunds`
Any invalid order	`except InvalidOrder`	`e instanceof InvalidOrder`
Anything PMXT	`except PmxtError`	`e instanceof PmxtError`

​Hierarchy

​HostedTradingError

​InsufficientEscrowBalance

​OrderSizeTooSmall

​InvalidApiKey

​OutcomeNotFound

​CatalogUnavailable

​BuiltOrderExpired

​InvalidSignature

​NoLiquidity

​MissingWalletAddress

​Catching by intent

​See also