Skip to main content
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)

CodeHTTP StatusDescriptionCommon CausesResolution
INVALID_PARAMS400Missing or invalid request parametersRequired parameter not provided; invalid chain ID; malformed token addressCheck the details field for the specific parameter and fix your request
VALIDATION_ERROR400Request body failed schema validationWrong data types; extra fields; nested object structure incorrectCompare your request body against the API documentation
SLIPPAGE_ERROR400Price moved beyond slippage toleranceMarket volatility; low liquidity pool; slippage too tightIncrease the slippage parameter or get a fresh quote
UNAUTHORIZED401Invalid or missing API keyWrong API key; expired key; accessing partner-only endpoint without a keyVerify your API key in the X-API-Key header
NO_ROUTE_FOUND404No swap route available for the given parametersUnsupported token pair; amount too low; no liquidity; chains not connectedTry different tokens, higher amounts, or wider slippage
RATE_LIMIT429Too many requestsExceeded 100 req/min (anonymous) or 2000 req/min (partner)Wait until meta.rateLimit.reset and implement exponential backoff

​
Server Errors (5xx)

CodeHTTP StatusDescriptionCommon CausesResolution
TRANSACTION_BUILD_FAILED500Failed to construct the swap transactionInsufficient balance; token approval needed; contract interaction failureRetry the request; if persistent, try a different route or tool
INTERNAL_ERROR500Unexpected server errorBug in the API server; database error; configuration issueRetry with exponential backoff; contact support if persistent
UPSTREAM_ERROR502Error from an upstream providerAn upstream routing provider returned an errorRetry after a brief delay; try excluding the failing tool with denyTools
RPC_FAILURE502Blockchain RPC node errorRPC node down; network congestion; chain reorganizationRetry after a brief delay
SERVICE_UNAVAILABLE503Service temporarily unavailableMaintenance; deployment; overwhelming trafficRetry with exponential backoff; check API status
TIMEOUT504Request timed outComplex route calculation; slow RPC responsesRetry with exponential backoff
UPSTREAM_TIMEOUT504Upstream provider timed outAn upstream provider took too long to respondRetry 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.