Error Codes

Canonical PAX API error catalog — 98 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.

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 be 24-char base62
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	HMAC timestamp outside ±300s window
401	NONCE_REUSED	HMAC nonce already seen within TTL
401	SIGNATURE_INVALID	HMAC signature does not match request
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
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

409 — conflict

HTTP	Code	Description
409	ALREADY_EXISTS	Resource with that identifier already exists
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
400	WEBHOOK_SECRET_INVALID	Webhook signing secret is malformed or missing
401	WEBHOOK_TIMESTAMP_SKEW	Webhook signature timestamp outside tolerance window
401	WEBHOOK_SIGNATURE_INVALID	Webhook signature does not verify against the presented body
422	WEBHOOK_EVENT_UNKNOWN	Webhook event_type not present in canonical catalog

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	INSUFFICIENT_BALANCE	Balance is insufficient for this operation

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	MCP tool name not registered
403	MCP_SCOPE_MISSING	MCP tool call missing required scope
501	MCP_NOT_IMPLEMENTED	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	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.