Error Codes Reference

{
  "code": 40001,
  "timestamp": "2026-02-05T10:30:00.000Z",
  "message": "Human readable error message",
  "details": {
    // Optional additional information
  }
}

{
  "code": 40002,
  "timestamp": "2026-02-05T10:30:00.000Z",
  "message": "Invalid parameter",
  "details": {
    "parameter": "resolution",
    "value": "2h",
    "allowed_values": ["1s", "1m", "5m", "15m", "1h", "4h", "1d"]
  }
}

{
  "code": 40006,
  "timestamp": "2026-02-05T10:30:00.000Z",
  "message": "Insufficient liquidity",
  "details": {
    "requested_amount": "1000000000",
    "available_liquidity": "500000000"
  }
}

{
  "code": 401,
  "timestamp": "2026-02-05T10:30:00.000Z",
  "message": "Unauthorized. Token is missing or invalid"
}

if (error.code === 401) {
  // Refresh token
  const newToken = await getAccessToken();
  // Retry request with new token
}

{
  "code": 403,
  "timestamp": "2026-02-05T10:30:00.000Z",
  "message": "Forbidden"
}

{
  "code": 40301,
  "timestamp": "2026-02-05T10:30:00.000Z",
  "message": "Insufficient permissions",
  "details": {
    "required_scope": "kyt.write",
    "current_scopes": ["kyt.read"]
  }
}

{
  "code": 40401,
  "timestamp": "2026-02-05T10:30:00.000Z",
  "message": "Liquidity pool not found",
  "details": {
    "chain": "sol",
    "pool_address": "INVALID_ADDRESS"
  }
}

{
  "code": 429,
  "timestamp": "2026-02-05T10:30:00.000Z",
  "message": "Too Many Requests. Rate limit reached",
  "details": {
    "limit": 100,
    "remaining": 0,
    "reset_at": 1706745600
  }
}

if (response.status === 429) {
  const retryAfter = response.headers.get('Retry-After') || 1;
  await sleep(retryAfter * 1000);
  // Retry request
}

{
  "code": 50010,
  "timestamp": "2026-02-05T10:30:00.000Z",
  "message": "DEX route build failed",
  "details": {
    "input_token": "So11111111111111111111111111111111111111112",
    "output_token": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
    "reason": "No valid route found"
  }
}

{
  "code": 51003,
  "timestamp": "2026-02-05T10:30:00.000Z",
  "message": "You have already claimed this red packet"
}

{
  "code": 52001,
  "timestamp": "2026-02-05T10:30:00.000Z",
  "message": "Webhooks endpoint limit reached",
  "details": {
    "current_count": 10,
    "max_allowed": 10
  }
}

import { ChainStreamClient } from '@chainstream-io/sdk';

const client = new ChainStreamClient(process.env.CHAINSTREAM_ACCESS_TOKEN);

async function safeApiCall(apiFunction) {
  try {
    return await apiFunction();
  } catch (error) {
    const { code, message, details } = error;
    
    // Handle errors by category
    if (code === 401) {
      // Authentication error: refresh token
      await refreshToken();
      return safeApiCall(apiFunction);
    }
    
    if (code === 429 || code === 42901 || code === 42902) {
      // Rate limit: wait and retry
      const retryAfter = details?.reset_at 
        ? (details.reset_at * 1000 - Date.now()) 
        : 1000;
      await sleep(retryAfter);
      return safeApiCall(apiFunction);
    }
    
    if (code >= 40000 && code < 41000) {
      // Client parameter error: log and throw
      console.error(`Parameter error: ${message}`, details);
      throw new ValidationError(message, details);
    }
    
    if (code >= 40400 && code < 40500) {
      // Resource not found
      console.warn(`Resource not found: ${message}`);
      return null;
    }
    
    if (code >= 50000) {
      // Server error: log and retry
      console.error(`Server error: ${message}`, details);
      await sleep(1000);
      return safeApiCall(apiFunction);
    }
    
    // Unknown error
    throw error;
  }
}

// Usage example
const tokenInfo = await safeApiCall(() => 
  client.token.getToken('sol', 'TOKEN_ADDRESS')
);