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

# Error Handling

> The Tide API uses conventional HTTP response codes and provides detailed error information to help you handle various error conditions gracefully.

## HTTP Status Codes

| Code | Status                | Description                               |
| ---- | --------------------- | ----------------------------------------- |
| 200  | OK                    | Request successful                        |
| 201  | Created               | Resource created successfully             |
| 400  | Bad Request           | Invalid request parameters                |
| 401  | Unauthorized          | Invalid or missing authentication         |
| 403  | Forbidden             | Insufficient permissions                  |
| 404  | Not Found             | Resource not found                        |
| 409  | Conflict              | Resource conflict (e.g., duplicate order) |
| 422  | Unprocessable Entity  | Valid request but business logic error    |
| 429  | Too Many Requests     | Rate limit exceeded                       |
| 500  | Internal Server Error | Server error                              |
| 502  | Bad Gateway           | Exchange adapter error                    |
| 503  | Service Unavailable   | Service temporarily unavailable           |

## Error Response Format

All errors follow a consistent JSON format:

```json theme={null}
{
  "error": {
    "code": 400,
    "type": "INVALID_PARAMETER",
    "message": "Invalid symbol",
    "details": "Symbol 'INVALID-PAIR' is not supported",
    "field": "symbol",
    "timestamp": 1698765432000,
    "requestId": "req_abc123456"
  }
}
```

## Common Error Types

### Authentication Errors

#### INVALID\_API\_KEY

```json theme={null}
{
  "error": {
    "code": 401,
    "type": "INVALID_API_KEY",
    "message": "Invalid API key",
    "details": "The provided API key is not valid or has been revoked"
  }
}
```

#### INVALID\_SIGNATURE

```json theme={null}
{
  "error": {
    "code": 401,
    "type": "INVALID_SIGNATURE",
    "message": "Invalid signature",
    "details": "The request signature does not match the expected value"
  }
}
```

### Trading Errors

#### INSUFFICIENT\_BALANCE

```json theme={null}
{
  "error": {
    "code": 422,
    "type": "INSUFFICIENT_BALANCE",
    "message": "Insufficient balance",
    "details": "Available balance: 1000.00 USDC, Required: 2000.00 USDC",
    "field": "quantity"
  }
}
```

#### ORDER\_NOT\_FOUND

```json theme={null}
{
  "error": {
    "code": 404,
    "type": "ORDER_NOT_FOUND",
    "message": "Order not found",
    "details": "Order with ID 'ord_1234567890' does not exist or has been canceled",
    "field": "orderId"
  }
}
```

### Smart Routing & Execution Errors

Smart order endpoints return errors with a top-level `success: false` payload instead of the nested `error` object used by legacy endpoints.

#### CREDENTIAL\_ERROR

```json theme={null}
{
  "success": false,
  "error": "Invalid Lighter private key format. Expected 64 or 80 hex characters.",
  "code": "CREDENTIAL_ERROR",
  "timestamp": 1234567890
}
```

#### ROUTING\_ERROR

```json theme={null}
{
  "success": false,
  "error": "No routing data available for DOGE. The symbol may not be supported.",
  "code": "ROUTING_ERROR",
  "timestamp": 1234567890
}
```

#### EXECUTION\_ERROR

```json theme={null}
{
  "success": false,
  "error": "Order execution failed: Insufficient balance",
  "code": "EXECUTION_ERROR",
  "details": "API Error 400: Insufficient USDC balance",
  "timestamp": 1234567890
}
```

### Rate Limiting Errors

#### RATE\_LIMIT\_EXCEEDED

```json theme={null}
{
  "error": {
    "code": 429,
    "type": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded",
    "details": "Too many requests. Limit: 60 requests per minute",
    "retryAfter": 30
  }
}
```

## Error Handling Best Practices

### 1. Implement Retry Logic

```javascript theme={null}
async function apiCallWithRetry(apiCall, maxRetries = 3) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      return await apiCall();
    } catch (error) {
      if (error.status === 429) {
        // Rate limit - wait and retry
        const retryAfter = error.retryAfter || Math.pow(2, attempt);
        await sleep(retryAfter * 1000);
        continue;
      }
      
      if (error.status >= 500 && attempt < maxRetries) {
        // Server error - exponential backoff
        await sleep(Math.pow(2, attempt) * 1000);
        continue;
      }
      
      // Don't retry client errors (4xx)
      throw error;
    }
  }
}
```

### 2. Handle Specific Error Types

```javascript theme={null}
async function placeOrder(orderData) {
  try {
    const response = await tideClient.placeOrder(orderData);
    return response;
  } catch (error) {
    switch (error.type) {
      case 'INSUFFICIENT_BALANCE':
        showError('Insufficient balance. Please deposit more funds.');
        break;
        
      case 'MIN_ORDER_SIZE':
        const minSize = extractMinSize(error.details);
        return placeOrder({ ...orderData, quantity: minSize });
        
      case 'RATE_LIMIT_EXCEEDED':
        await sleep(error.retryAfter * 1000);
        return placeOrder(orderData);
        
      default:
        console.error('Unexpected error:', error);
        showError('An unexpected error occurred. Please try again.');
    }
  }
}
```

## Support and Debugging

When reporting errors:

1. **Include the `requestId`** from the error response
2. **Provide the full error response** (sanitize sensitive data)
3. **Include request details** (endpoint, parameters, timestamp)
4. **Describe the expected behavior**

Contact support:

* **X (Twitter)**: [@tide\_ag](https://x.com/tide_ag)
* **Telegram**: [@tidedotag](https://t.me/tidedotag)

<Warning>
  Always validate input parameters before making API calls to avoid unnecessary errors and rate limit consumption.
</Warning>