> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chainworks.org/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 |
| `402` | Monthly credit allowance exhausted |
| `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 |

### Account Errors

| Code | Description | Solution |
| - | - | - |
| `CREDIT_LIMIT_EXCEEDED` | Monthly credit allowance and overage are exhausted | Wait for the UTC month to roll over, or change plan. See [Pricing](https://docs.chainworks.org/pricing.md) |

`CREDIT_LIMIT_EXCEEDED` arrives with HTTP `402` and is not retryable - the same request keeps failing until the month rolls over or the plan changes. Free routes such as `/svm/price/unsubscribe`, `/svm/wallet-tracker/untrack`, and `/evm/autosnipe/remove` keep working while an account is over its limit, so standing work can always be wound down.

### 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",
        "CREDIT_LIMIT_EXCEEDED",
      ];
      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)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.