> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chainworks.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Error Handling

> Error codes, shapes, and recovery strategies for Chainworks API responses over Socket.IO and HTTP.

The Chainworks API uses consistent error responses across all endpoints.

***

## Error Response Format

When a request fails, you receive an error response:

```json theme={null}
{
  "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.

### Both transports share this envelope

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

```typescript theme={null}
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

```python theme={null}
@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:

```typescript theme={null}
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

1. **Check the console** - Log full responses to see error details
2. **Use the playground** - Test requests interactively at [/playground](https://chainworks.co/playground)
3. **Validate addresses** - Ensure addresses are correct for the target chain
4. **Check token contract** - Some tokens have transfer restrictions
5. **Monitor connection** - Ensure WebSocket connection is stable

***

## Getting Help

If you encounter persistent errors:

1. Note the error code and message
2. Capture the full request parameters
3. Contact us at [info@chainworks.co](mailto:info@chainworks.co)