All API errors share one shape:
{
"status": "error",
"code": "ERROR_CODE",
"message": "Human-readable explanation",
"details": { ... }
}
Top-level codes
| Code | HTTP | What it means | Recovery |
|---|
BAD_REQUEST | 400 | Validation failed (missing/invalid field) | Check details for field-level errors |
UNAUTHORIZED | 401 | API key missing or invalid | Re-issue key; check header format |
FORBIDDEN | 403 | Endpoint blocked for this key | Check route permissions |
NOT_FOUND | 404 | Resource (chain, token, txId) doesn’t exist | Verify inputs |
RATE_LIMITED | 429 | Per-IP or per-key cap hit | Backoff; honor retryAfter |
INTERNAL_SERVER_ERROR | 500 | Routing/upstream failure | Retry; if persistent, contact support |
BAD_GATEWAY | 502 | Upstream protocol unavailable | Retry; route may be temporarily un-quotable |
Routing-specific codes
| Code | Meaning |
|---|
NO_ROUTE_FOUND | No DEX/bridge can route this pair at this size |
INSUFFICIENT_LIQUIDITY | Route exists but liquidity is too thin |
SLIPPAGE_TOO_TIGHT | Estimated output below minReturn; loosen slippage |
AMOUNT_TOO_SMALL | Below provider minimum (often $1 equivalent) |
AMOUNT_TOO_LARGE | Above provider maximum (route-specific) |
UNSUPPORTED_TOKEN | Token not in any supported pool |
UNSUPPORTED_CHAIN | Chain not in supported set |
UNSUPPORTED_PAIR | Tokens supported individually but not as a pair |
Contract-revert errors
When the on-chain transaction reverts, DZap surfaces a structured ContractErrorResponse:
{
"status": "error",
"code": "CONTRACT_REVERT",
"message": "Slippage exceeded",
"details": {
"action": "swap",
"provider": "paraswap",
"reason": "minOut not met",
"txHash": "0x..."
}
}
details.action is the failing leg of a multi-step bundle. Useful for surfacing UI hints (e.g. “swap leg 2 reverted”).
Programmatic handling
try {
const quotes = await dzap.getTradeQuotes({ ... });
} catch (e: any) {
if (e.code === 'NO_ROUTE_FOUND') {
// suggest different tokens/amounts
} else if (e.code === 'RATE_LIMITED') {
await sleep(e.retryAfter * 1000);
return retry();
} else {
throw e;
}
}
{ code, message, details } regardless of upstream source. Last modified on May 4, 2026
