Errors and recovery

Branch on error.code, not on the message text. Preserve the server's requestId so a failure can be traced without logging credentials or signatures.

Standard error shape

Most customer endpoints return this envelope:

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "A human-readable explanation",
    "details": {}
  },
  "requestId": "<server-request-id>"
}

details is optional and depends on the error. Treat it as diagnostic data; validate its shape before reading nested fields. HTTP status describes the broad failure class, while the code identifies the specific condition.

The DexTools adapter follows its own contract and returns { code, message, issues }. Do not parse it as the standard envelope.

Common errors

Code	Recovery
`AMBIGUOUS_CREDENTIALS`	Send a bearer token or an API key, never both.
`API_KEY_INVALID` / `API_KEY_REVOKED`	Check the key and network; replace a revoked key.
`API_KEY_IP_NOT_ALLOWED`	Check the integration's public egress IP against the key's allowlist.
`API_KEY_SCOPE_REQUIRED`	Use a key with the required scope.
`API_KEY_ROUTE_NOT_ALLOWED`	The route does not accept this key. Use its documented authentication flow.
`API_KEY_PARTY_NOT_AUTHORIZED`	Use the wallet connection for the Party that authorized this trade key.
`API_KEY_TIMESTAMP_OUT_OF_WINDOW`	Synchronize the client clock and sign a fresh request. Check `details.serverTime` when present.
`API_KEY_SIGNATURE_INVALID`	Verify the canonical message, encoding, body bytes, and replay handling.
`AUTHENTICATION_REQUIRED` / `INVALID_ACCESS_TOKEN` / `SESSION_REVOKED`	Sign in again through the product's supported session flow.
`RATE_LIMITED`	Respect `Retry-After` and reduce shared request traffic.
`VALIDATION_FAILED`	Correct the fields identified by the response and retry only after correction.
`INVALID_CURSOR`	Restart pagination with a valid cursor and matching filters.
`IDEMPOTENCY_KEY_REQUIRED` / `INVALID_IDEMPOTENCY_KEY`	Supply a valid idempotency key for the write.
`IDEMPOTENCY_KEY_CONFLICT`	Reuse the original body for this key, or create a new key for a genuinely new operation.
`QUOTE_EXPIRED`	Request and review a fresh quote.
`QUOTE_VENUE_CHANGED` / `MARKET_GRADUATION_IN_PROGRESS`	Refresh the market and quote after the lifecycle transition.
`QUOTE_WALLET_CHANGED` / `QUOTE_WALLET_MISMATCH`	Requote for the wallet that will submit the order.
`DEPOSIT_INSUFFICIENT_BALANCE` / `DEPOSIT_INSUFFICIENT_FUNDS`	Check the account's available trading balance before placing another order.
`ORDER_NOT_OPEN`	Refresh order status; it may already have filled, expired, or been cancelled.
`POOL_PAUSED`	Do not submit more orders to that pool until it becomes available.
`REPREPARE_REQUIRED` / `PREPARE_EXPIRED` / `LEDGER_PREPARATION_EXPIRED`	Prepare a fresh transaction from a valid quote and review it again.
`PRODUCT_LEGAL_ACCEPTANCE_REQUIRED`	Complete the current legal acceptance through the signed-in app flow.
`MARKET_DATA_API_KEY_REQUIRED`	Send a valid customer read key.
`LEDGER_UNAVAILABLE` / `CANTON_UNAVAILABLE`	Reconcile existing operations and use bounded retries after service recovery.

Unknown codes and compatibility

The registry is additive: a newer server can return a code your client does not yet know. Show a safe generic failure, preserve the request ID, and keep the operation available for reconciliation. Never guess success or retry a trade solely because a code is unfamiliar.

Framework failures can use HTTP_<status>, such as HTTP_404, in addition to the named codes below.

IDEMPOTENCY_CONFLICT is a deprecated alias of IDEMPOTENCY_KEY_CONFLICT. Current write routes return the latter. Handle both while supporting older responses.

Complete code registry

The following 358 named codes match the public schema snapshot checked on October 28, 2026. The shared registry includes codes for other backend runtimes and disabled features; inclusion does not mean every code can be returned by every customer endpoint. Endpoint response definitions remain the guide to a particular request.

Download the machine-readable registry or inspect the live schema for newer additions.

API keys

AMBIGUOUS_CREDENTIALS
API_KEYS_UNAVAILABLE
API_KEY_AUTHORIZATION_EXPIRED
API_KEY_AUTHORIZATION_INVALID
API_KEY_AUTHORIZATION_REQUIRED
API_KEY_AUTHORIZATION_USED
API_KEY_INVALID
API_KEY_IP_NOT_ALLOWED
API_KEY_LIMIT_REACHED
API_KEY_NOT_FOUND
API_KEY_PARTY_NOT_AUTHORIZED
API_KEY_REVOKED
API_KEY_ROUTE_NOT_ALLOWED
API_KEY_SCOPE_REQUIRED
API_KEY_SIGNATURE_INVALID
API_KEY_SIGNING_KEY_INVALID
API_KEY_SIGNING_KEY_REQUIRED
API_KEY_SIGNING_KEY_UNUSED
API_KEY_TIMESTAMP_OUT_OF_WINDOW

Account and authentication

ACCOUNT_CLOSURE_CONFIRMATION_REQUIRED
ACCOUNT_CLOSURE_STEP_UP_NOT_CONFIGURED
ACCOUNT_CLOSURE_UNAVAILABLE
ACCOUNT_RESTRICTED
ANONYMOUS_ACCOUNT_NOT_ALLOWED
AUTHENTICATION_REQUIRED
AUTHENTICATION_UNAVAILABLE
AUTHORIZATION_UNAVAILABLE
AUTH_HYBRID_MIGRATION_EXPIRED
AUTH_PREVIEW_IDENTITY_CAPACITY_REACHED
AVATAR_AUTH_PROVIDER_UNSUPPORTED
AVATAR_CLEANUP_AUTH_REQUIRED
AVATAR_DELETION_FAILED
AVATAR_PATH_INVALID
AVATAR_UPLOAD_INVALID
AVATAR_UPLOAD_NOT_FOUND
CUSTOM_AVATAR_NOT_FOUND
CUSTOM_AVATAR_NOT_PUBLISHED
CUSTOM_AVATAR_UPLOAD_NOT_CONFIGURED
HANDLE_UNAVAILABLE
INVALID_ACCESS_TOKEN
INVALID_AUTHORIZATION_HEADER
PRODUCT_ACCOUNT_RESTRICTED
PRODUCT_LEGAL_ACCEPTANCE_REQUIRED
PRODUCT_LEGAL_ACCEPTANCE_UNAVAILABLE
PRODUCT_LEGAL_POLICY_MISMATCH
PROFILE_NOT_FOUND
PROFILE_VERSION_CONFLICT
SESSION_REVOCATION_PROVIDER_UNSUPPORTED
SESSION_REVOCATION_UNAVAILABLE
SESSION_REVOKED
SIGNUP_ALLOWLIST_ADMIN_KEY_REQUIRED
SIGNUP_ALLOWLIST_UNAVAILABLE
SIGNUP_NOT_INVITED
USERNAME_CHANGE_COOLDOWN
USERNAME_CHANGE_LIMIT_REACHED
USERNAME_IMMUTABLE
USERNAME_RESERVED
USERNAME_UNAVAILABLE

Trading and liquidity

AMM_FEE_ROUNDS_TO_ZERO
AMM_INPUT_OUT_OF_RANGE
AMM_OUTPUT_ROUNDS_TO_ZERO
AMM_SLIPPAGE_EXCEEDED
AMM_TRADE_BELOW_MINIMUM
BAD_ECONOMICS
BAD_FEE_CONFIG
BAD_SUPPLY
CURVE_030_FEATURE_DISABLED
CURVE_ALREADY_GRADUATED
CURVE_BUY_EXCEEDS_GRADUATION
CURVE_BUY_STRANDS_GRADUATION
CURVE_FEE_ROUNDS_TO_ZERO
CURVE_GRADUATION_NOT_REACHED
CURVE_MIN_CC_OUT_NOT_MET
CURVE_MIN_TOKEN_OUT_NOT_MET
CURVE_OUTPUT_ROUNDS_TO_ZERO
CURVE_SELL_EXCEEDS_SOLD_TOKENS
CURVE_SELL_STRANDS_RESIDUAL
CURVE_TOKEN_AMOUNT_OUT_OF_RANGE
CURVE_TRADE_BELOW_MINIMUM
FEE_CHANGE_COOLDOWN
FEE_CLAIM_INTENT_CONFLICT
FEE_CLAIM_INTENT_NOT_FOUND
FEE_CLAIM_NOT_CREATOR
FEE_STEP_TOO_LARGE
HOLDINGS_FRAGMENTED
INSTRUMENT_NOT_HELD
INSUFFICIENT_PREVIEW_BALANCE
MARKET_GRADUATION_IN_PROGRESS
MINIMUM_ALLOCATION_UNAVAILABLE
NOTHING_TO_CLAIM
OPENING_BUY_EXCEEDS_CURVE
OPENING_BUY_FEE_ROUNDS_TO_ZERO
OPENING_BUY_ROUNDING_UNREPRESENTABLE
OPENING_BUY_STRANDS_GRADUATION
OPENING_BUY_TOO_SMALL
ORDER_NOT_OPEN
POOL_PAUSED
POSITION_PROJECTION_NOT_CONFIGURED
PREPARE_EXPIRED
QUOTE_EXPIRED
QUOTE_NOT_FOUND
QUOTE_VENUE_CHANGED
QUOTE_WALLET_CHANGED
QUOTE_WALLET_MISMATCH
REPREPARE_REQUIRED
SWAP_CURVE_CAPACITY_EXCEEDED
SWAP_MINIMUM_OUTPUT_NOT_MET
SWAP_OUTPUT_ROUNDS_TO_ZERO
SWAP_QUOTE_ADAPTER_NOT_CONFIGURED
SWAP_QUOTE_ALREADY_BOUND
SWAP_QUOTE_AMOUNT_OUT_OF_RANGE
SWAP_QUOTE_INVALID
SWAP_QUOTE_MODEL_CHANGED
SWAP_QUOTE_PREVIEW_CAPACITY_REACHED
SWAP_QUOTE_UNPRICEABLE
SWAP_SELL_EXCEEDS_RELEASED_TOKENS
SWAP_SELL_STRANDS_RESIDUAL
SWAP_TRADE_BELOW_MINIMUM
TRADE_INTENT_NOT_FOUND
TRADING_REFERRALS_UNAVAILABLE
TRADING_REFERRAL_NOT_FOUND

Launches and media

APPLICATION_DOCUMENTS_INCOMPLETE
APPLICATION_DOCUMENT_ALREADY_REGISTERED
APPLICATION_DOCUMENT_METADATA_MISMATCH
APPLICATION_DOCUMENT_UPLOAD_NOT_FOUND
APPLICATION_EVIDENCE_NOT_CLEARED
APPLICATION_INCOMPLETE
APPLICATION_LOCKED
APPLICATION_NOT_FOUND
APPLICATION_STATE_CHANGED
APPLICATION_SUBMISSION_EVIDENCE_MISSING
DOCUMENT_ACCESS_CONFLICT_OF_INTEREST
DOCUMENT_APPLICATION_NOT_REVIEWABLE
DOCUMENT_DOWNLOAD_GRANT_STATE_CHANGED
DOCUMENT_NOT_CLEARED
DOCUMENT_NOT_CURRENT_SUBMISSION
DOCUMENT_NOT_FOUND
DOCUMENT_PURPOSE_NOT_AUTHORIZED
DOCUMENT_UPLOAD_AUTH_PROVIDER_UNSUPPORTED
DOCUMENT_UPLOAD_QUOTA_EXCEEDED
GOVERNED_ISSUER_WORKFLOW_NOT_RELEASED
LAUNCH_APPLICATION_PREVIEW_CAPACITY_REACHED
LAUNCH_MEDIA_ANIMATION_UNSUPPORTED
LAUNCH_MEDIA_CONTENT_MISMATCH
LAUNCH_MEDIA_DESCRIPTOR_MISMATCH
LAUNCH_MEDIA_DIGEST_MISMATCH
LAUNCH_MEDIA_DIMENSIONS_UNSAFE
LAUNCH_MEDIA_FILE_REQUIRED
LAUNCH_MEDIA_ICON_TOO_SMALL
LAUNCH_MEDIA_INVALID_IMAGE
LAUNCH_MEDIA_MALWARE_DETECTED
LAUNCH_MEDIA_NOT_FOUND
LAUNCH_MEDIA_NOT_PUBLISHED
LAUNCH_MEDIA_PIPELINE_NOT_CONFIGURED
LAUNCH_MEDIA_PREVIEW_CAPACITY_REACHED
LAUNCH_MEDIA_REJECTED
LAUNCH_MEDIA_ROLE_MISMATCH
LAUNCH_MEDIA_SCAN_UNAVAILABLE
LAUNCH_MEDIA_STORAGE_UNAVAILABLE
LAUNCH_MEDIA_TOO_LARGE
LAUNCH_MEDIA_TYPE_UNSUPPORTED
LAUNCH_MEDIA_UPLOAD_CONSUMED
LAUNCH_MEDIA_UPLOAD_EXPIRED
LAUNCH_MEDIA_UPLOAD_NOT_FOUND
LAUNCH_NOT_FOUND
LAUNCH_NOT_OPEN
LAUNCH_PARTICIPATION_ADAPTER_NOT_CONFIGURED
MEDIA_NOT_FOUND
MEDIA_NOT_PUBLISHED
PROJECT_SLUG_UNAVAILABLE
TICKER_INVALID
TICKER_RESERVATION_MISMATCH
TICKER_TAKEN
TOKEN_LAUNCH_ADAPTER_NOT_CONFIGURED
TOKEN_LAUNCH_CREATION_FEE_CHANGED
TOKEN_LAUNCH_CREATION_FEE_NOT_SUPPORTED
TOKEN_LAUNCH_CREATION_FEE_UNSET
TOKEN_LAUNCH_INSUFFICIENT_BALANCE
TOKEN_LAUNCH_OPENING_BUY_NOT_SUPPORTED
TOKEN_LAUNCH_PERMIT_EXPIRED
TOKEN_LAUNCH_PERMIT_NOT_FOUND
TOKEN_LAUNCH_QUOTE_ALREADY_BOUND
TOKEN_LAUNCH_QUOTE_EXPIRED
TOKEN_LAUNCH_QUOTE_INTEGRITY_FAILED
TOKEN_LAUNCH_QUOTE_MODEL_CHANGED
TOKEN_LAUNCH_QUOTE_NOT_FOUND
TOKEN_LAUNCH_QUOTE_PREVIEW_CAPACITY_REACHED
TOKEN_LAUNCH_RECORD_INVALID
TOKEN_LAUNCH_REGISTRAR_NOT_FOUND
TOKEN_LAUNCH_REGISTRAR_TERMS_INVALID
TOKEN_LAUNCH_REQUEST_EXPIRED
TOKEN_LAUNCH_REQUEST_NOT_FOUND
TOKEN_LAUNCH_SUPPLY_INVALID
TOKEN_LAUNCH_SUPPLY_NOT_ALLOWED
TOKEN_LAUNCH_SUPPLY_SELECTION_NOT_ENABLED
TOKEN_LAUNCH_WALLET_CONTEXT_CHANGED
TOKEN_NOT_FOUND
TOKEN_WALLET_METADATA_NOT_FOUND
UPLOAD_INTENT_EXPIRED
UPLOAD_INTENT_NOT_FOUND
UPLOAD_INTENT_STATE_CHANGED

Wallets, deposits, and operations

ACTIVITY_NOT_FOUND
ACTIVITY_PROJECTION_INVALID
ACTIVITY_PROJECTION_NOT_CONFIGURED
DEPOSIT_BALANCE_STALE
DEPOSIT_FROZEN
DEPOSIT_INSTRUCTIONS_NOT_CONFIGURED
DEPOSIT_INSUFFICIENT_BALANCE
DEPOSIT_INSUFFICIENT_FUNDS
DEPOSIT_LEDGER_SHARD_UNAVAILABLE
DEPOSIT_NOT_FOUND
DEPOSIT_REFERENCE_REUSED
OPERATION_EXPIRED
OPERATION_EXPIRY_MISSING
OPERATION_NOT_FOUND
OPERATION_PROJECTION_INVALID
OPERATION_STATE_CHANGED
RECIPIENT_IS_SENDER
VALUATION_ACCOUNT_MISMATCH
WALLET_BINDING_RIGHTS_UNAVAILABLE
WALLET_CHALLENGE_ALREADY_USED
WALLET_CHALLENGE_EXPIRED
WALLET_CHALLENGE_INVALID
WALLET_CONNECTION_INVALID
WALLET_CONNECTION_NOT_FOUND
WALLET_CONNECTION_RACE
WALLET_NETWORK_CONFLICT
WALLET_NOT_OWNED
WALLET_ORIGIN_INVALID
WALLET_ORIGIN_NOT_ALLOWED
WALLET_ORIGIN_REQUIRED
WALLET_PARTY_ALREADY_CONNECTED
WALLET_PARTY_BINDING_LOCKED
WALLET_PARTY_NOT_BINDABLE
WALLET_PARTY_NOT_HOSTED
WALLET_PROJECTION_INCOMPLETE
WALLET_PROJECTION_NOT_CONFIGURED
WALLET_REPORT_CONFLICT
WALLET_SIGNATURE_INVALID
WALLET_SIGNATURE_VERIFIER_NOT_CONFIGURED
WITHDRAWAL_MEMO_INVALID
WITHDRAWAL_NOT_FOUND
WITHDRAWAL_PAYOUT_STARTED

Market data

CATALOG_PROJECTION_NOT_CONFIGURED
CREATOR_PROJECTION_NOT_CONFIGURED
CREATOR_REWARD_PARTY_SOURCE_MISMATCH
HISTORY_BUSY
MARKET_ASSET_NOT_FOUND
MARKET_BLOCK_NOT_FOUND
MARKET_BLOCK_RANGE_TOO_LARGE
MARKET_DATA_API_KEY_INVALID
MARKET_DATA_API_KEY_REQUIRED
MARKET_DATA_DISABLED
MARKET_EXCHANGE_NOT_FOUND
MARKET_PAIR_NOT_FOUND
SUPERAPP_ACTIVITY_PROJECTION_NOT_CONFIGURED
SUPERAPP_MARKET_PROJECTION_NOT_CONFIGURED
USD_CANDLES_NOT_CONFIGURED

Ledger and infrastructure

CANTON_PREVIEW_CAPACITY_REACHED
CANTON_UNAVAILABLE
DATABASE_UNAVAILABLE
DA_CONFIGURATION_FAILED
LEDGER_APPLICATION_PARTY_NOT_CONFIGURED
LEDGER_CONTRACT_STALE
LEDGER_CURVE_PACKAGE_NOT_PINNED
LEDGER_MARKET_NOT_FOUND
LEDGER_MARKET_SNAPSHOT_INVALID
LEDGER_PARTY_NOT_HOSTED
LEDGER_PREPARATION_EXPIRED
LEDGER_PREPARATION_FAILED
LEDGER_READ_FAILED
LEDGER_REGISTRAR_MISSING
LEDGER_ROUTE_NOT_SUPPORTED
LEDGER_SUBMISSION_REJECTED
LEDGER_UNAVAILABLE
QUEUE_UNAVAILABLE
REDIS_UNAVAILABLE
SCANNER_UNAVAILABLE
STORAGE_CALLER_AUTH_UNAVAILABLE
STORAGE_INSPECTION_FAILED
STORAGE_SIGNING_FAILED
STORAGE_UNAVAILABLE
UNSAFE_AUTH_CONFIGURATION
UNSAFE_MOCK_NETWORK
UNSAFE_PREVIEW_WALLET_VERIFIER

Request handling

IDEMPOTENCY_CONFLICT
IDEMPOTENCY_KEY_CONFLICT
IDEMPOTENCY_KEY_REQUIRED
INTERNAL_ERROR
INVALID_APPLICATION_STATE
INVALID_CURSOR
INVALID_IDEMPOTENCY_KEY
INVALID_MOCK_USER
INVALID_OPERATION_STATE
INVALID_SUBMISSION_EVIDENCE
INVALID_WITHDRAWAL_STATE
NOT_FOUND
RATE_LIMITED
RATE_LIMITER_UNAVAILABLE
REQUEST_DEADLINE_EXCEEDED
RESPONSE_SCHEMA_VIOLATION
VALIDATION_FAILED

Other product and runtime codes

ADMIN_ACCESS_REQUIRED
ADMIN_AUDIT_WRITE_FAILED
ADMIN_AUTHORITY_CHANGED
ADMIN_AUTHORIZATION_UNAVAILABLE
ADMIN_CAPABILITY_REQUIRED
ADMIN_CONFLICT_REGISTRY_UNAVAILABLE
ADMIN_MFA_REQUIRED
ADMIN_OUTBOX_WRITE_FAILED
ADMIN_REAUTHENTICATION_REQUIRED
ADMIN_REVIEW_IDEMPOTENCY_CAPACITY_REACHED
ADMIN_ROLE_NOT_AUTHORIZED
ADMIN_ROLE_SELECTION_INVALID
ADMIN_ROLE_SELECTION_REQUIRED
ADMIN_SESSION_REVOKED
COMMITMENT_OUTSIDE_LIMITS
CONTROL_REVIEWS_REQUIRED
CRITICAL_RISK_UNRESOLVED
FINAL_APPROVAL_STATE_INVALID
INTERACTIVE_SESSION_REQUIRED
MISSION_CONTROL_CATEGORY_INVALID
MISSION_CONTROL_FEE_POLICY_INVALID
MISSION_CONTROL_IDEMPOTENCY_CAPACITY_REACHED
MISSION_CONTROL_LAUNCH_EXISTS
MISSION_CONTROL_LAUNCH_NOT_FOUND
MISSION_CONTROL_NO_CHANGE
MISSION_CONTROL_PRICE_INVALID
MISSION_CONTROL_PROJECTION_UNAVAILABLE
MISSION_CONTROL_REASON_REQUIRED
MISSION_CONTROL_TAG_INVALID
MISSION_CONTROL_TAXONOMY_EXISTS
MISSION_CONTROL_TAXONOMY_IMMUTABLE
MISSION_CONTROL_TAXONOMY_IN_USE
MISSION_CONTROL_TAXONOMY_NOT_FOUND
MISSION_CONTROL_USER_NOT_FOUND
MISSION_CONTROL_VERSION_CONFLICT
MOCK_IDENTITY_SELECTION_NOT_ALLOWED
NOVA_WAITLIST_NOT_ENABLED
NOVA_WAITLIST_PREVIEW_CAPACITY_REACHED
POINTS_PROGRAM_NOT_CONFIGURED
PREVIEW_CONFIRMATION_REQUIRED
PREVIEW_IDENTITY_CAPACITY_EXCEEDED
PREVIEW_MARKET_INSTRUMENT_NOT_FOUND
PREVIEW_MARKET_SNAPSHOT_INVALID
PREVIEW_OPERATION_CAPACITY_REACHED
PREVIEW_WALLET_CHALLENGE_CAPACITY_REACHED
PREVIEW_WALLET_CONNECTION_CAPACITY_REACHED
PREVIEW_WALLET_FIXTURE_REQUIRED
REVIEW_CONFLICT_OF_INTEREST
REVIEW_DECISION_NOT_AUTHORIZED
REVIEW_KIND_NOT_AUTHORIZED
SERVICE_ACT_AS_REQUIRED
SERVICE_PARTY_NOT_ALLOWED
SERVICE_PRINCIPAL_BIND_UNAVAILABLE
SERVICE_PRINCIPAL_NOT_ALLOWED
WORKFORCE_IDENTITY_NOT_PROVISIONED
WORKFORCE_IDENTITY_REQUIRED

Standard error shape#

Common errors#

Unknown codes and compatibility#

Complete code registry#