Error Codes

Every error response includes a machine-readable code field in the error object. Use these codes to build targeted error handling in your application.

Error Response Format

{
  "data": null,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "Human-readable description",
    "details": { ... }
  },
  "meta": {
    "requestId": "uuid",
    "timestamp": 1711234567,
    "rateLimit": { ... }
  }
}

Complete Error Code Reference

Client Errors (4xx)

Code	HTTP Status	Description	Common Causes	Resolution
`INVALID_PARAMS`	400	Missing or invalid request parameters	Required parameter not provided; invalid chain ID; malformed token address	Check the `details` field for the specific parameter and fix your request
`VALIDATION_ERROR`	400	Request body failed schema validation	Wrong data types; extra fields; nested object structure incorrect	Compare your request body against the API documentation
`INVALID_BODY`	400	Request body could not be parsed or was empty	POST/PUT request with no JSON body; malformed JSON; wrong Content-Type	Set `Content-Type: application/json` and send a non-empty JSON body
`SLIPPAGE_ERROR`	400	Price moved beyond slippage tolerance	Market volatility; low liquidity pool; slippage too tight	Increase the `slippage` parameter or get a fresh quote
`PARTNER_FEE_EXCEEDS_MAX`	400	Configured partner fee exceeds the platform maximum	Partner fee config has a value above the platform’s allowed cap	Contact Hypermid support to negotiate higher fee terms
`PARTNER_WALLET_NOT_REGISTERED`	400	Partner fee wallet not registered for this ecosystem	Swap settles to an ecosystem (e.g. solana, near) where you have no fee wallet	Register a wallet via `PUT /v1/partner/me/fee-wallets`
`ECOSYSTEM_NOT_CONFIGURED`	400	Requested ecosystem is not configured for this partner	Trying to use NEAR Intents / Tron / etc. before the ecosystem is enabled for your account	Contact Hypermid support to enable the ecosystem for your partner account
`UNAUTHORIZED`	401	Invalid or missing API key	Wrong API key; expired key; accessing partner-only endpoint without a key	Verify your API key in the `X-API-Key` header
`NO_ROUTE_FOUND`	404	No swap route available for the given parameters	Unsupported token pair; amount too low; no liquidity; chains not connected	Try different tokens, higher amounts, or wider slippage
`RATE_LIMIT`	429	Too many requests	Exceeded 30 req/min (anonymous) or 100 req/min (partner)	Wait until `meta.rateLimit.reset` and implement exponential backoff

Server Errors (5xx)

Code	HTTP Status	Description	Common Causes	Resolution
`TRANSACTION_BUILD_FAILED`	500	Failed to construct the swap transaction	Insufficient balance; token approval needed; contract interaction failure	Retry the request; if persistent, try a different route or tool
`INTERNAL_ERROR`	500	Unexpected server error	Bug in the API server; database error; configuration issue	Retry with exponential backoff; contact support if persistent
`UPSTREAM_ERROR`	502	Error from an upstream provider	An upstream routing provider returned an error	Retry after a brief delay; try excluding the failing tool with `denyTools`
`RPC_FAILURE`	502	Blockchain RPC node error	RPC node down; network congestion; chain reorganization	Retry after a brief delay
`UPSTREAM_MAINTENANCE`	503	Upstream provider is in scheduled maintenance	LI.FI, NEAR Intents, or RampNow announced a maintenance window	Wait and retry; check upstream provider status pages for the window
`SERVICE_UNAVAILABLE`	503	Hypermid is temporarily unavailable	Maintenance; deployment; overwhelming traffic	Retry with exponential backoff; check API status
`TIMEOUT`	504	Request timed out	Complex route calculation; slow RPC responses	Retry with exponential backoff
`UPSTREAM_TIMEOUT`	504	Upstream provider timed out	An upstream provider took too long to respond	Retry after a delay; consider using a different tool

Error Handling Example

import { Hypermid, HypermidError } from "@hypermid/sdk";

const client = new Hypermid({ apiKey: "your-api-key" });

try {
  const quote = await client.getQuote({ ... });
} catch (error) {
  if (error instanceof HypermidError) {
    switch (error.code) {
      case "INVALID_PARAMS":
        // Fix the request
        console.error("Bad request:", error.details);
        break;

      case "NO_ROUTE_FOUND":
        // Inform user, suggest alternatives
        console.log("No route found. Try a different token pair.");
        break;

      case "SLIPPAGE_ERROR":
        // Increase slippage and retry
        console.log("Price changed. Retrying with higher slippage...");
        break;

      case "RATE_LIMIT":
        // Wait and retry
        const waitMs = (error.rateLimit.reset - Date.now() / 1000) * 1000;
        await new Promise((r) => setTimeout(r, waitMs));
        break;

      case "UPSTREAM_ERROR":
      case "RPC_FAILURE":
      case "UPSTREAM_TIMEOUT":
      case "TIMEOUT":
      case "INTERNAL_ERROR":
      case "SERVICE_UNAVAILABLE":
        // Retry with backoff
        console.log("Transient error. Retrying...");
        break;

      default:
        console.error("Unknown error:", error.code);
    }
  }
}

For comprehensive error handling patterns, see the Error Handling Guide.

Getting Started

Guides

Resources

Error Response Format

Complete Error Code Reference

Client Errors (4xx)

Server Errors (5xx)

Error Handling Example

​Error Response Format

​Complete Error Code Reference

​Client Errors (4xx)

​Server Errors (5xx)

​Error Handling Example

Error Response Format

Complete Error Code Reference

Client Errors (4xx)

Server Errors (5xx)

Error Handling Example