Skip to main content

Error Handling

This page documents error codes and error handling patterns.

Standard Error Codes​

Use the predefined error codes from NodeError.errorCodes:

// Common error codes
NodeError.errorCodes.UnsupportedNode     // NODE_000
NodeError.errorCodes.MissingInputToken   // NODE_001
NodeError.errorCodes.MissingOutputToken  // NODE_002
NodeError.errorCodes.UnsupportedToken    // NODE_003
NodeError.errorCodes.UnsupportedChain    // NODE_004
NodeError.errorCodes.SwapDisabled       // NODE_005
NodeError.errorCodes.InvalidAmount       // NODE_006
NodeError.errorCodes.NetworkError        // NODE_007
NodeError.errorCodes.Internal            // NODE_008
NodeError.errorCodes.ParsingError        // NODE_009
NodeError.errorCodes.RpcError            // NODE_010
NodeError.errorCodes.NotFound            // NODE_011
NodeError.errorCodes.DatabaseError       // NODE_012
NodeError.errorCodes.InactiveNode        // NODE_013
NodeError.errorCodes.NodeStateError      // NODE_014
NodeError.errorCodes.ApiError            // NODE_015
NodeError.errorCodes.InvalidMode         // NODE_016
NodeError.errorCodes.CustomError         // NODE_998
NodeError.errorCodes.Other               // NODE_999

Error Handling Patterns​

Pattern 1: API Error Handling​

try {
  const response = await fetch(url);
  if (!response.ok) {
    return new NodeError(
      `API request failed: ${response.statusText}`,
      NodeError.errorCodes.ApiError
    );
  }
  return await response.json();
} catch (error) {
  return new NodeError(
    `Network error: ${error.message}`,
    NodeError.errorCodes.NetworkError
  );
}

Pattern 2: Validation Error Handling​

if (!input.input_token) {
  return new NodeError(
    "Input token is required",
    NodeError.errorCodes.MissingInputToken
  );
}

Pattern 3: Business Logic Error Handling​

if (!this.isSwapEnabled(input.input_token, input.output_token)) {
  return new NodeError(
    "Swap not supported for this token pair",
    NodeError.errorCodes.SwapDisabled
  );
}

Error Code Selection Guide​

ScenarioError Code
Missing required input tokenMissingInputToken
Missing required output tokenMissingOutputToken
Token not supportedUnsupportedToken
Chain not supportedUnsupportedChain
Swap not available for pairSwapDisabled
Invalid amount formatInvalidAmount
Network/API call failedNetworkError
API returned errorApiError
Transaction not foundNotFound
Internal processing errorInternal
Parsing/format errorParsingError
RPC call failedRpcError
Node state sync failedNodeStateError

Real-World Examples​

Meson Error Handling​

Location: ts/src/nodes/meson/common.ts

  • Enriches API errors with decoded error.code
  • Provides friendly messages (e.g., amount-over-limit)
  • Pre-validates against /limits to avoid API errors

NEAR Error Handling​

Location: ts/src/nodes/near/common.ts

  • Sets reasonable timeouts
  • Distinguishes between 400 vs. 500 responses
  • Provides guidance for different error types

GasZip Error Handling​

Location: ts/src/nodes/gaszip/common.ts

  • Uses AbortController timeouts
  • Returns structured NodeError when request aborts
  • Handles capacity and limit errors gracefully

Best Practices​

  1. Use Appropriate Error Codes: Choose the most specific error code
  2. Provide Clear Messages: Include helpful error messages
  3. Handle Errors Early: Validate inputs before expensive operations
  4. Don't Swallow Errors: Always return or propagate errors
  5. Log Errors: Log errors for debugging while returning user-friendly messages

Next Steps​