Error Codes

Complete reference of all Hypermid API 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
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
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
SERVICE_UNAVAILABLE	503	Service 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.