Error Codes

Canonical PAX API error catalog — 102 codes across 15 groups. All errors return the envelope {"error":{"code","message","trace_id","details?"}}. Auto-generated from packages/core/src/errors.ts on every deploy.

A subset of codes below are reserved for gated features — enterprise HMAC auth, MCP tooling, and receiver-side webhook verification — and are not returned by the standard live surface today. Endpoints that can actually return each code are listed on the per-endpoint OpenAPI page (/openapi). If you see an undocumented code in production, contact support with the trace_id.

Error response format

{
  "error": {
    "code":     "TIER_LIMIT_EXCEEDED",
    "message":  "order notional 50.00 exceeds tier max_order_usdt 10",
    "trace_id": "a98efc1d-7db7-4ee2-bba6-afe481418c11",
    "details":  { "tier": "self_serve", "cap": "10" }
  }
}

The HTTP status is bound to the code via the shared error catalog — the same code always returns the same status. Reference the trace_id when contacting support.

400 — client errors

HTTP	Code	Description
400	BAD_REQUEST	Malformed request body or query
400	VALIDATION_FAILED	Payload did not pass schema validation
400	IDEMPOTENCY_KEY_MISSING	Idempotency-Key header required on writes
400	IDEMPOTENCY_KEY_MALFORMED	Idempotency-Key must match [A-Za-z0-9_-]{8,128}
409	IDEMPOTENCY_BODY_MISMATCH	Idempotency key reused with different body
400	URN_MALFORMED	Identifier not a canonical URN
400	URN_INVALID_DOMAIN	Identifier URN domain unrecognized
400	URN_INVALID_SLUG	Identifier URN slug malformed
400	URN_SLUG_TOO_LONG	Identifier URN slug exceeds 128 chars
400	ID_MALFORMED	Identifier not a canonical prefixed id
400	ID_INVALID_KIND	Identifier prefix unrecognized

401 — authentication

HTTP	Code	Description
401	AUTH_REQUIRED	Missing credentials
401	AUTH_INVALID	Credentials rejected
401	WRONG_ENV_KEY	Key's tier flag does not match the requested capability (e.g. self_serve key attempting an over-cap trade)
401	TIMESTAMP_SKEW	reserved · enterprise HMAC. Presented HMAC timestamp is more than 300 seconds off server clock. Standard integrations use Bearer.
401	NONCE_REUSED	reserved · enterprise HMAC. Presented HMAC nonce reused within 600s TTL. Generate a fresh random nonce per request.
401	SIGNATURE_INVALID	reserved · enterprise HMAC. On the current live surface any HMAC-shaped credential returns AUTH_INVALID with a directive to use Bearer.
401	TOKEN_EXPIRED	OAuth access token expired
401	TOKEN_REVOKED	OAuth access token revoked
401	TOKEN_INVALID	OAuth access token could not be verified
400	PKCE_INVALID	PKCE code_verifier did not match code_challenge
400	AUTH_CODE_EXPIRED	OAuth authorization code has expired
400	AUTH_CODE_CONSUMED	OAuth authorization code has already been used
400	REDIRECT_URI_MISMATCH	redirect_uri does not match the value bound at authorize time
401	REFRESH_TOKEN_REUSED	Refresh token reuse detected — token family revoked

403 — authorization

HTTP	Code	Description
403	SCOPE_MISSING	Required scope not present on credential
403	SCOPE_NOT_ALLOWED	Requested scope is not in the app allowed_scopes list
403	STEP_UP_MFA_REQUIRED	High-friction scope requires step-up MFA verification
403	BUILDER_NOT_APPROVED	Builder identity is not in approved status
403	APP_NOT_APPROVED	App is not in approved status
403	APP_DISABLED	App has been disabled by owner or admin
403	DELEGATION_MISSING	on_behalf_of requires signed delegation grant
403	DELEGATION_EXPIRED	Delegation grant has expired
403	JURISDICTION_BLOCKED	This action is not permitted in this jurisdiction
403	SANCTIONS_HIT	Wallet address matches a sanctions list; registration or payout blocked
404	SANDBOX_ONLY	Endpoint only available in sandbox environment
404	PROD_ONLY	Endpoint disabled in sandbox environment

404

HTTP	Code	Description
404	NOT_FOUND	Resource not found (generic — route or record not present)
404	MARKET_NOT_FOUND	Market ID does not exist (specific — surfaces inside handlers that need a valid market before proceeding, e.g. subaccount transfer, MM quote creation, RFQ)

409 — conflict

HTTP	Code	Description
409	ALREADY_EXISTS	Resource with that identifier already exists
409	CONFLICT	Uniqueness constraint hit (e.g. same address registered on the same currency+network)
409	STATE_CONFLICT	Requested transition not valid from current state
409	IDEMPOTENCY_IN_FLIGHT	A prior request with the same key is still processing

422 — semantic

HTTP	Code	Description
422	RISK_LIMIT_BREACH	Order would breach a configured risk limit
422	BUILDER_FEE_ABOVE_CAP	Requested builder_fee_bps exceeds apps.builder_fee_cap_bps
422	MARKET_HALTED	Market currently halted by circuit breaker
422	MARKET_CLOSED	Market is past close time
422	MARKET_NOT_APPROVED	Market template proposal is not yet approved
422	MARKET_TEMPLATE_UNKNOWN	Template id not found
422	MARKET_TEMPLATE_PARAM_INVALID	Template param failed validation
422	ORACLE_ADAPTER_UNKNOWN	Oracle adapter not registered
422	ORACLE_DISAGREEMENT	Oracle adapters disagreed beyond max deviation
422	RESOLUTION_LOCKED	Resolution challenge window still open
422	DISPUTE_ALREADY_OPEN	A dispute is already open on this market
422	ANTI_ABUSE_BLOCKED	Trade flagged by anti-abuse rules (wash/self/related-party)
422	OPERATOR_AGREEMENT_MISSING	Operator requires signed agreement before this action

429

HTTP	Code	Description
429	RATE_LIMITED	Rate limit exceeded, retry after Retry-After
429	TIER_LIMIT_EXCEEDED	Order or daily notional exceeds api_key tier caps
403	TIER_UPGRADE_REQUIRED	This endpoint requires a higher trust tier
429	SANDBOX_KEY_DAILY_LIMIT	This IP has already minted a sandbox key today
401	PASSWORD_INCORRECT	Current password does not match
422	PASSWORD_TOO_WEAK	New password does not meet strength requirements

webhook subsystem

HTTP	Code	Description
400	WEBHOOK_URL_INVALID	Webhook URL must be a valid https URL with no userinfo/fragment (thrown by PAX on POST /v1/webhooks)
400	WEBHOOK_SECRET_INVALID	receiver-side. Recommended code for your webhook receiver to return when it cannot decode the signing secret. Not emitted by PAX; PAX emits WEBHOOK_URL_INVALID at register time.
401	WEBHOOK_TIMESTAMP_SKEW	receiver-side. Recommended code for your receiver to return when the t= value in X-PAX-Signature is outside your tolerance window. Not emitted by PAX.
401	WEBHOOK_SIGNATURE_INVALID	receiver-side. Recommended code for your receiver to return when neither v1= HMAC matches the body. See /webhook-signing.
422	WEBHOOK_EVENT_UNKNOWN	Webhook event_type not present in canonical catalog (thrown by PAX on POST /v1/webhooks and PATCH /v1/webhooks/{id})

subaccounts / delegation

HTTP	Code	Description
409	SUBACCOUNT_LABEL_TAKEN	A subaccount with this label already exists
409	SUBACCOUNT_HAS_BALANCE	Cannot close subaccount with nonzero balance
409	SUBACCOUNT_HAS_POSITIONS	Cannot close subaccount with open positions
409	SUBACCOUNT_HAS_OPEN_ORDERS	Cannot close subaccount with open orders
403	SUBACCOUNT_FROZEN	Subaccount is frozen
403	DELEGATION_SCOPE_MISMATCH	Partner API key lacks required delegation:trade scope
422	DELEGATION_DAILY_CAP_EXCEEDED	Delegation daily notional cap exceeded
422	BALANCE_INSUFFICIENT	Balance is insufficient for this operation (e.g. subaccount transfer, order placement)

composer

HTTP	Code	Description
400	TEMPLATE_SCHEMA_INVALID	Template params_schema is malformed
400	TEMPLATE_DISPLAY_KEY_MISSING	display_defaults references a key not in params_schema
409	PROPOSAL_STATE_INVALID	Proposal state transition not valid
422	COMBO_COMPONENT_HALTED	Combo derived market has a halted component
403	COMPLIANCE_GATE_BLOCKED	Compliance gate blocked market creation

liquidity/RFQ

HTTP	Code	Description
400	QUOTE_EXPIRED_IN_PAST	Quote expires_at_ms must be in the future
400	QUOTE_SIZE_INVALID	Quote size is invalid (must be > 0)
409	RFQ_NOT_OPEN	RFQ is not open for new quotes
422	RFQ_QUOTE_OUT_OF_BOUNDS	RFQ quote price outside min/max bounds
422	INCENTIVE_BUDGET_EXCEEDED	Incentive budget for this period is exhausted

widget / data / MCP

HTTP	Code	Description
404	MCP_TOOL_UNKNOWN	reserved · MCP subsystem. MCP tool name not registered
403	MCP_SCOPE_MISSING	reserved · MCP subsystem. MCP tool call missing required scope
501	MCP_NOT_IMPLEMENTED	reserved · MCP subsystem. MCP tool has no upstream implementation yet
403	WIDGET_ORIGIN_BLOCKED	Widget embed origin is blocked
403	DATA_TIER_EXCEEDED	Data query exceeds allowed tier
422	DATA_RANGE_TOO_LARGE_FOR_TIER	Requested range exceeds tier maximum

oracle / resolution

HTTP	Code	Description
502	ORACLE_ADAPTER_ERROR	Oracle adapter fetch failed
403	ORACLE_BOND_INSUFFICIENT	Oracle provider bond below configured minimum
422	RESOLUTION_EVIDENCE_MISSING	Resolution requires evidence and none was attached
409	RESOLUTION_CHALLENGE_OPEN	Cannot finalize while a challenge window is open

marketplace

HTTP	Code	Description
403	LISTING_NOT_APPROVED	Marketplace listing has not been approved
409	BOUNTY_ALREADY_CLAIMED	Bounty has already been claimed

500 — / 502 / 503 / 504

HTTP	Code	Description
500	INTERNAL_ERROR	An internal error occurred
502	UPSTREAM_ERROR	Upstream service returned an error
504	UPSTREAM_TIMEOUT	Upstream service timeout
503	SERVICE_UNAVAILABLE	Named subsystem is currently gated off (e.g. payouts kill-switch on for a scope), with a human-readable reason in the message
503	MAINTENANCE	Service temporarily in maintenance

Canonical source

This table is generated from packages/core/src/errors.ts. To propose a new code, PR that file; do not edit this HTML directly. See OpenAPI spec for which codes each endpoint can return.