> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dzap.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Error Codes

> Errors you'll see, what they mean, and how to recover.

All API errors share one shape:

```json theme={null}
{
  "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`:

```json theme={null}
{
  "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

```ts theme={null}
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;
  }
}
```

The SDK normalizes errors to `{ code, message, details }` regardless of upstream source.