Error Codes

DZap’s error model has two layers: execution errors returned when a transaction is submitted/simulated, and contract-revert errors surfaced when the on-chain call itself reverts.

Two failure shapes do not follow the patterns below:

429 responses use their own body (error, retryAfter, resetTime, limit, window) — see Rate Limits.
Per-pair quote errors are not thrown. /v1/quotes returns 200 with the failure carried inside the pair object as status: "error" and a message, alongside pairs that succeeded. Check each pair, not just the HTTP status.

Execution status codes

StatusCodes, used in code fields across the SDK (e.g. DZapTransactionResponse.code):

Code	Value	Meaning
`Success`	`200`	Operation succeeded
`UserRejectedRequest`	`4001`	User rejected the signature/transaction in their wallet
`WalletRPCFailure`	`429`	Wallet RPC call failed or was rate-limited
`SimulationFailure`	`417`	Transaction simulation failed before submission
`FunctionNotFound`	`32771`	Contract function selector not found (ABI/version mismatch)
`Error`	`500`	Generic failure
`ContractExecutionError`	`-500`	On-chain execution reverted

Transaction status

Every SDK execution result (trade(), zap(), tradeGasless()) reports one of these in its status field: mining · success · rejected · error · reverted · pendingWalletConfirmation · partialSuccess · waitingForExecution

type DZapTransactionResponse = {
  status: TxnStatus;
  errorMsg?: string;
  code: StatusCodes | number;
  action?: "TRY_ANOTHER_ROUTE" | "INCREASE_SLIPPAGE" | "INCREASE_ALLOWANCE";
  txnHash?: string;
  error?: unknown;
  additionalInfo?: Record<string, unknown>;
  updatedQuotes?: Record<string, string>;
};

Contract-revert errors and recovery actions

When execution fails, the response may include an action hint telling you how to recover:

Action	Meaning	Recovery
`TRY_ANOTHER_ROUTE`	The selected provider/route failed	Retry using `bestReturnSource` (or the next `quoteRates` entry) instead of `recommendedSource`
`INCREASE_SLIPPAGE`	Output moved outside the slippage bound	Re-quote with a higher `slippage` value
`INCREASE_ALLOWANCE`	Token allowance is insufficient for the amount	Call `approve()` again before retrying

const tradeResult = await dzap.trade({ request, signer });

if (tradeResult.status !== "success") {
  switch (tradeResult.action) {
    case "TRY_ANOTHER_ROUTE": {
      // rebuild request with quotes[pairKey].bestReturnSource
      break;
    }
    case "INCREASE_SLIPPAGE": {
      // re-quote with a higher slippage value
      break;
    }
    case "INCREASE_ALLOWANCE": {
      // call approve() again
      break;
    }
    default:
      console.error(tradeResult.errorMsg);
  }
}

Unavailable routes

When individual providers fail but the pair still quotes, they appear under quotes[pairKey].unavailableRoutes, keyed by provider, as a ProtocolErrorInfo. The type field selects which details shape you get:

`type`	`reason` values	Extra `details`
`AMOUNT`	`AMOUNT_TOO_LOW`, `AMOUNT_TOO_HIGH`, `AMOUNT_OUT_OF_RANGE`	`minAmount`, `maxAmount`, `token`, `decimals`
`ROUTE`	`NO_ROUTE`, `UNSUPPORTED_PAIR`, `INSUFFICIENT_LIQUIDITY`, `UNSUPPORTED_TOKEN`, `UNSUPPORTED_CHAIN`	`providerMessage`
`SLIPPAGE`	—	`providerMessage`
`UNKNOWN`	—	`providerMessage`

AMOUNT errors carry minAmount/maxAmount in the token’s base units — surface the actual bound to the user rather than guessing a threshold.

Status endpoint terminal states

/v1/status (Trade) and /v1/status (Fuse) both report a terminal status field once the transaction settles:

Trade (TradeStatusResponse.status, and per-leg TxStatusForPair.status): COMPLETED · FAILED · PENDING · PARTIAL · REFUNDED
Fuse (ZapStatusResponse.status, and per-step ZapStatusStep.status): PENDING · COMPLETED · FAILED · REFUNDED

See Track Trade Status and Track Zap Status for polling examples.

Getting started

Fuse API

Trade API

Error Codes

Execution status codes

Transaction status

Contract-revert errors and recovery actions

Unavailable routes

Status endpoint terminal states

​Execution status codes

​Transaction status

​Contract-revert errors and recovery actions

​Unavailable routes

​Status endpoint terminal states

Execution status codes

Transaction status

Contract-revert errors and recovery actions

Unavailable routes

Status endpoint terminal states