Errors & Status Codes

Complete guide to error handling and HTTP status codes

Error Object Format

All error responses follow a consistent format:

{
  "error": true,
  "error_code": "ERROR_CODE",
  "message": "Human-readable error message",
  "details": {
    // Optional additional error details
  }
}

HTTP Status Codes

Status Code	Meaning	Common Causes
200	Success	Request completed successfully
400	Bad Request	Invalid parameters, missing required fields
401	Unauthorized	Invalid or missing API key, invalid signature
403	Forbidden	API key lacks required permissions
404	Not Found	Invalid endpoint or resource not found
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Server-side error, try again later
503	Service Unavailable	Service temporarily unavailable, maintenance

Common Error Codes

LIMIT_MIN

The requested amount is below the minimum exchange limit for this currency pair.

{
  "error": true,
  "error_code": "LIMIT_MIN",
  "message": "Amount is below minimum limit",
  "min_amount": 0.01,
  "requested_amount": 0.005
}

LIMIT_MAX

The requested amount exceeds the maximum exchange limit for this currency pair.

{
  "error": true,
  "error_code": "LIMIT_MAX",
  "message": "Amount exceeds maximum limit",
  "max_amount": 1000.0,
  "requested_amount": 1500.0
}

OFFLINE

The requested currency pair is temporarily unavailable for exchange.

{
  "error": true,
  "error_code": "OFFLINE",
  "message": "Currency pair BTC/USDT is temporarily offline"
}

RESERVE

Insufficient reserves to complete the exchange. The requested amount exceeds available liquidity.

{
  "error": true,
  "error_code": "RESERVE",
  "message": "Insufficient reserves for this exchange",
  "available_amount": 500.0,
  "requested_amount": 1000.0
}

MAINTENANCE

The service is undergoing scheduled maintenance. Check status page for updates.

{
  "error": true,
  "error_code": "MAINTENANCE",
  "message": "Service is under maintenance",
  "estimated_resume": "2025-01-27T12:00:00Z"
}

INVALID_ADDRESS

The provided destination address is invalid for the specified network.

{
  "error": true,
  "error_code": "INVALID_ADDRESS",
  "message": "Destination address is invalid for network ERC20"
}

RATE_EXPIRED

The fixed rate has expired. Request a new rate before creating the order.

{
  "error": true,
  "error_code": "RATE_EXPIRED",
  "message": "Fixed rate has expired. Please request a new rate."
}

INVALID_SIGNATURE

The request signature is invalid. Check your signature generation algorithm.

{
  "error": true,
  "error_code": "INVALID_SIGNATURE",
  "message": "Request signature is invalid"
}

TIMESTAMP_EXPIRED

The request timestamp is too old or too far in the future. Ensure your server clock is synchronized.

{
  "error": true,
  "error_code": "TIMESTAMP_EXPIRED",
  "message": "Request timestamp is outside acceptable range"
}

Best Practices for Error Handling

✓Check error_code, not just HTTP status - The error_code provides specific information about what went wrong
✓Handle rate limits gracefully - Implement exponential backoff when receiving 429 responses
✓Validate before sending - Check amounts against min/max limits before creating orders
✓Log errors for debugging - Include error_code and message in your error logs
✓Provide user-friendly messages - Translate technical error codes into user-friendly messages
✓Retry transient errors - Retry 500 and 503 errors with exponential backoff

Error Handling Example

async function handleApiError(response) {
  if (!response.ok) {
    const error = await response.json();
    
    switch (error.error_code) {
      case 'LIMIT_MIN':
      case 'LIMIT_MAX':
        // Show user-friendly message with limits
        return `Amount must be between ${error.min_amount} and ${error.max_amount}`;
      
      case 'RATE_EXPIRED':
        // Request a new rate
        return 'Rate expired. Please try again.';
      
      case 'INVALID_ADDRESS':
        // Ask user to check address
        return 'Invalid destination address. Please check and try again.';
      
      case 'RESERVE':
        // Suggest lower amount
        return `Insufficient liquidity. Maximum available: ${error.available_amount}`;
      
      case 'OFFLINE':
      case 'MAINTENANCE':
        // Show maintenance message
        return 'Service temporarily unavailable. Please try again later.';
      
      case 'RATE_LIMIT_EXCEEDED':
        // Implement backoff
        const retryAfter = error.retry_after || 60;
        await sleep(retryAfter * 1000);
        return null; // Retry
      
      default:
        return error.message || 'An unexpected error occurred';
    }
  }
  
  return null;
}