Error Handling

The Chainworks API uses consistent error responses across all endpoints.

Error Response Format

When a request fails, you receive an error response:

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error description"
  },
  "partialResult": {
    // Optional: helpful data even when the request fails
  }
}

The partialResult field may contain useful information even when the request fails, such as partial token data or pool information. The success and error envelope is identical on Socket.IO and HTTP. A successful response always has success: true and a result field; responses may also include optional rateLimit and serverTimings objects. Over Socket.IO, the response arrives on the event you emitted. Over HTTP, the same JSON is returned in the response body, and the HTTP status code reflects the outcome:

HTTP Status	Meaning
`200`	Success (`success: true`)
`400`	Client error such as invalid input or authentication failure
`500`	Internal server error

Even on a 400 or 500, the body still follows the error envelope above, so you can read error.code and error.message the same way on both transports.

Common Error Codes

Connection Errors

Code	Description	Solution
`UNAUTHORIZED`	Invalid or expired auth token	Check your API credentials
`CONNECTION_TIMEOUT`	Server didn’t respond in time	Retry the request
`RATE_LIMITED`	Too many requests	Implement backoff and retry

Request Errors

Code	Description	Solution
`INVALID_CHAIN`	Unsupported chain identifier	Use `eth`, `base`, `bsc`, or `sol`
`INVALID_TOKEN`	Token address not found	Verify the token contract address
`NOT_A_TOKEN`	Address is not a valid token mint or does not exist on chain	Verify the mint address for the target chain
`INVALID_WALLET`	Invalid wallet address format	Check the address format
`INVALID_AMOUNT`	Amount is zero or negative	Provide a valid positive amount
`MISSING_PARAMETER`	Required parameter not provided	Include all required parameters

Trading Errors

Code	Description	Solution
`INSUFFICIENT_LIQUIDITY`	Not enough liquidity for trade	Reduce trade size or try later
`PRICE_IMPACT_TOO_HIGH`	Trade would cause excessive slippage	Reduce trade size
`TOKEN_NOT_TRADEABLE`	Token trading is restricted	Check token contract for restrictions
`NO_ROUTE_FOUND`	No DEX route available	Token may not have liquidity

Transaction Errors

Code	Description	Solution
`INSUFFICIENT_BALANCE`	Wallet lacks funds	Add funds to wallet
`APPROVAL_REQUIRED`	Token approval needed	Call approve endpoint first
`TRANSACTION_SIMULATION_FAILED`	Transaction would revert	Check parameters and balances
`NONCE_TOO_LOW`	Transaction nonce already used	Use a higher nonce

Handling Errors

TypeScript

socket.on("/evm/buy/quote", (response) => {
  if (response.success) {
    console.log("Quote:", response.result);
  } else {
    const { code, message } = response.error;

    switch (code) {
      case "INSUFFICIENT_LIQUIDITY":
        console.log("Not enough liquidity. Try a smaller amount.");
        break;
      case "INVALID_TOKEN":
        console.log("Token not found. Check the address.");
        break;
      default:
        console.error(`Error ${code}: ${message}`);
    }

    // partialResult may contain useful info
    if (response.partialResult) {
      console.log("Partial data:", response.partialResult);
    }
  }
});

Python

@sio.on("/evm/buy/quote")
def on_quote(response):
    if response.get("success"):
        print("Quote:", response["result"])
    else:
        error = response["error"]
        code = error["code"]
        message = error["message"]

        if code == "INSUFFICIENT_LIQUIDITY":
            print("Not enough liquidity. Try a smaller amount.")
        elif code == "INVALID_TOKEN":
            print("Token not found. Check the address.")
        else:
            print(f"Error {code}: {message}")

        if "partialResult" in response:
            print("Partial data:", response["partialResult"])

Retry Strategy

For transient errors, implement exponential backoff:

async function requestWithRetry(path: string, params: object, maxRetries = 3): Promise<any> {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      const response = await makeRequest(path, params);

      if (response.success) {
        return response.result;
      }

      // Don't retry certain errors
      const noRetry = ["INVALID_TOKEN", "INVALID_WALLET", "UNAUTHORIZED"];
      if (noRetry.includes(response.error.code)) {
        throw new Error(response.error.message);
      }

      // Exponential backoff
      const delay = Math.pow(2, attempt) * 1000;
      await new Promise((resolve) => setTimeout(resolve, delay));
    } catch (error) {
      if (attempt === maxRetries - 1) {
        throw error;
      }
    }
  }
}

Debugging Tips

Check the console - Log full responses to see error details
Use the playground - Test requests interactively at /playground
Validate addresses - Ensure addresses are correct for the target chain
Check token contract - Some tokens have transfer restrictions
Monitor connection - Ensure WebSocket connection is stable

Getting Help

If you encounter persistent errors:

Note the error code and message
Capture the full request parameters
Contact us at info@chainworks.co

Getting Started

SVM (Solana)

EVM Chains

Reference

Error Response Format

Common Error Codes

Connection Errors

Request Errors

Trading Errors

Transaction Errors

Handling Errors

TypeScript

Python

Retry Strategy

Debugging Tips

Getting Help

​Error Response Format

​Both transports share this envelope

​Common Error Codes

​Connection Errors

​Request Errors

​Trading Errors

​Transaction Errors

​Handling Errors

​TypeScript

​Python

​Retry Strategy

​Debugging Tips

​Getting Help

Error Response Format

Both transports share this envelope

Common Error Codes

Connection Errors

Request Errors

Trading Errors

Transaction Errors

Handling Errors

TypeScript

Python

Retry Strategy

Debugging Tips

Getting Help