Back to Documentation

Error Codes

Comprehensive reference for all error codes, their meanings, and troubleshooting steps to resolve common issues.

HTTP Status Codes

2xx Success Codes

200 OK

Description: Request completed successfully.

Common Scenarios:

  • Successful API request
  • Order placed successfully
  • Data retrieved successfully

Response Example:

{
    "status": "success",
    "data": {
        "orderId": "12345678-1234-1234-1234-123456789012",
        "status": "pending"
    }
}

201 Created

Description: Resource created successfully.

Common Scenarios:

  • New order created
  • Account created
  • API key generated

Response Example:

{
    "status": "created",
    "data": {
        "accountId": "acc_123456789",
        "status": "active"
    }
}

4xx Client Error Codes

400 Bad Request

Description: Invalid request format or parameters.

Common Causes:

  • Missing required parameters
  • Invalid parameter values
  • Malformed JSON

Error Examples:

{
    "error": "invalid_request",
    "message": "Missing required parameter: symbol",
    "code": 400,
    "details": {
        "missing_parameters": ["symbol"],
        "provided_parameters": ["side", "quantity"]
    }
}

Troubleshooting:

  1. Check request format and parameters
  2. Verify all required fields are included
  3. Validate parameter values
  4. Review API documentation

401 Unauthorized

Description: Authentication failed or missing.

Common Causes:

  • Invalid API key
  • Missing authentication headers
  • Expired credentials

Error Examples:

{
    "error": "unauthorized",
    "message": "Invalid API key",
    "code": 401,
    "details": {
        "reason": "api_key_invalid"
    }
}

Troubleshooting:

  1. Verify API key is correct
  2. Check authentication headers
  3. Ensure API key has required permissions
  4. Generate new API key if needed

403 Forbidden

Description: Access denied due to insufficient permissions.

Common Causes:

  • Insufficient account permissions
  • API key lacks required permissions
  • Resource access restricted

Error Examples:

{
    "error": "forbidden",
    "message": "Insufficient permissions for this operation",
    "code": 403,
    "details": {
        "required_permission": "write:orders",
        "current_permissions": ["read:account"]
    }
}

Troubleshooting:

  1. Check account permissions
  2. Verify API key permissions
  3. Upgrade account if needed
  4. Contact support for permission issues

404 Not Found

Description: Requested resource not found.

Common Causes:

  • Invalid endpoint URL
  • Resource doesn't exist
  • Incorrect resource ID

Error Examples:

{
    "error": "not_found",
    "message": "Order not found",
    "code": 404,
    "details": {
        "resource_type": "order",
        "resource_id": "12345678-1234-1234-1234-123456789012"
    }
}

Troubleshooting:

  1. Verify endpoint URL is correct
  2. Check resource ID exists
  3. Ensure resource belongs to your account
  4. Review API documentation

429 Too Many Requests

Description: Rate limit exceeded.

Common Causes:

  • Too many requests per second
  • Daily request limit exceeded
  • Burst limit exceeded

Error Examples:

{
    "error": "rate_limit_exceeded",
    "message": "Too many requests. Please slow down.",
    "code": 429,
    "details": {
        "limit": 100,
        "remaining": 0,
        "reset_time": 1640995260
    }
}

Troubleshooting:

  1. Implement exponential backoff
  2. Reduce request frequency
  3. Use WebSocket for real-time data
  4. Upgrade account for higher limits

5xx Server Error Codes

500 Internal Server Error

Description: Unexpected server error.

Common Causes:

  • Server-side processing error
  • Database connection issues
  • Third-party service failures

Error Examples:

{
    "error": "internal_server_error",
    "message": "An unexpected error occurred",
    "code": 500,
    "details": {
        "request_id": "req_123456789"
    }
}

Troubleshooting:

  1. Retry the request after a delay
  2. Check system status page
  3. Contact support if issue persists
  4. Provide request ID for debugging

502 Bad Gateway

Description: Invalid response from upstream server.

Common Causes:

  • Upstream service unavailable
  • Network connectivity issues
  • Service overload

Troubleshooting:

  1. Retry the request
  2. Check system status
  3. Contact support if issue persists

503 Service Unavailable

Description: Service temporarily unavailable.

Common Causes:

  • Maintenance in progress
  • Service overload
  • Planned downtime

Error Examples:

{
    "error": "service_unavailable",
    "message": "Service temporarily unavailable",
    "code": 503,
    "details": {
        "retry_after": 300,
        "maintenance_window": "2024-01-15T20:00:00Z to 2024-01-15T22:00:00Z"
    }
}

Troubleshooting:

  1. Wait for service to resume
  2. Check maintenance schedule
  3. Retry after specified time
  4. Monitor status page for updates

Trading Error Codes

Order Errors

ORDER_INVALID_SYMBOL

Description: Invalid trading pair symbol.

Error Code: ORDER_INVALID_SYMBOL

Common Causes:

  • Symbol format incorrect
  • Unsupported trading pair
  • Market not available

Example:

{
    "error": "ORDER_INVALID_SYMBOL",
    "message": "The symbol 'INVALID/USD' is not supported",
    "code": 400,
    "details": {
        "provided_symbol": "INVALID/USD",
        "supported_symbols": ["BTC/USD", "ETH/USD", "BNB/USD"]
    }
}

Troubleshooting:

  1. Check symbol format (e.g., "BTC/USD")
  2. Verify symbol is supported
  3. Use symbol list endpoint to get valid symbols

ORDER_INSUFFICIENT_BALANCE

Description: Insufficient account balance for order.

Error Code: ORDER_INSUFFICIENT_BALANCE

Common Causes:

  • Not enough funds in account
  • Funds locked in other orders
  • Currency mismatch

Example:

{
    "error": "ORDER_INSUFFICIENT_BALANCE",
    "message": "Insufficient balance to place order",
    "code": 400,
    "details": {
        "required": 5000.00,
        "available": 4500.00,
        "currency": "USD"
    }
}

Troubleshooting:

  1. Check account balance
  2. Deposit additional funds
  3. Cancel pending orders to free up funds
  4. Verify currency is correct

ORDER_INVALID_QUANTITY

Description: Invalid order quantity.

Error Code: ORDER_INVALID_QUANTITY

Common Causes:

  • Quantity below minimum
  • Quantity above maximum
  • Invalid decimal places

Example:

{
    "error": "ORDER_INVALID_QUANTITY",
    "message": "Invalid order quantity",
    "code": 400,
    "details": {
        "provided_quantity": 0.00001,
        "minimum_quantity": 0.001,
        "maximum_quantity": 1000.0
    }
}

Troubleshooting:

  1. Check minimum/maximum quantity limits
  2. Ensure correct decimal places
  3. Verify quantity format

ORDER_INVALID_PRICE

Description: Invalid order price.

Error Code: ORDER_INVALID_PRICE

Common Causes:

  • Price below minimum
  • Price above maximum
  • Invalid decimal places
  • Price too far from market

Example:

{
    "error": "ORDER_INVALID_PRICE",
    "message": "Invalid order price",
    "code": 400,
    "details": {
        "provided_price": 0.01,
        "minimum_price": 0.1,
        "current_market_price": 50000.00
    }
}

Troubleshooting:

  1. Check price limits
  2. Ensure correct decimal places
  3. Verify price is reasonable
  4. Use market order for immediate execution

Account Errors

ACCOUNT_NOT_VERIFIED

Description: Account verification required.

Error Code: ACCOUNT_NOT_VERIFIED

Common Causes:

  • KYC verification incomplete
  • Documents under review
  • Verification rejected

Example:

{
    "error": "ACCOUNT_NOT_VERIFIED",
    "message": "Account verification required for this operation",
    "code": 403,
    "details": {
        "verification_status": "pending",
        "required_documents": ["id_document", "proof_of_address"]
    }
}

Troubleshooting:

  1. Complete KYC verification
  2. Upload required documents
  3. Wait for verification approval
  4. Contact support if verification is delayed

ACCOUNT_TRADING_DISABLED

Description: Trading disabled for account.

Error Code: ACCOUNT_TRADING_DISABLED

Common Causes:

  • Account suspended
  • Trading restrictions
  • Compliance issues

Example:

{
    "error": "ACCOUNT_TRADING_DISABLED",
    "message": "Trading is currently disabled for your account",
    "code": 403,
    "details": {
        "reason": "account_suspended",
        "contact_support": true
    }
}

Troubleshooting:

  1. Contact support immediately
  2. Check account status
  3. Resolve any compliance issues
  4. Follow support instructions

Market Data Errors

MARKET_DATA_UNAVAILABLE

Description: Market data not available.

Error Code: MARKET_DATA_UNAVAILABLE

Common Causes:

  • Market closed
  • Data feed issues
  • Symbol not traded

Example:

{
    "error": "MARKET_DATA_UNAVAILABLE",
    "message": "Market data not available for this symbol",
    "code": 404,
    "details": {
        "symbol": "BTC/USD",
        "reason": "market_closed",
        "next_open": "2024-01-16T09:00:00Z"
    }
}

Troubleshooting:

  1. Check market hours
  2. Verify symbol is active
  3. Wait for market to open
  4. Contact support if issue persists

SIGNAL_NOT_AVAILABLE

Description: AI signal not available.

Error Code: SIGNAL_NOT_AVAILABLE

Common Causes:

  • Insufficient data
  • Model processing error
  • Account type limitations

Example:

{
    "error": "SIGNAL_NOT_AVAILABLE",
    "message": "AI signal not available for this symbol",
    "code": 404,
    "details": {
        "symbol": "BTC/USD",
        "reason": "insufficient_data",
        "retry_after": 300
    }
}

Troubleshooting:

  1. Wait for more data to be available
  2. Check account type for signal access
  3. Retry after specified time
  4. Contact support if issue persists

WebSocket Error Codes

Connection Errors

WS_CONNECTION_FAILED

Description: WebSocket connection failed.

Error Code: WS_CONNECTION_FAILED

Common Causes:

  • Network connectivity issues
  • Firewall blocking
  • Server unavailable

Troubleshooting:

  1. Check internet connection
  2. Verify firewall settings
  3. Try different network
  4. Contact support if issue persists

WS_AUTHENTICATION_FAILED

Description: WebSocket authentication failed.

Error Code: WS_AUTHENTICATION_FAILED

Common Causes:

  • Invalid API credentials
  • Expired credentials
  • Insufficient permissions

Troubleshooting:

  1. Verify API key and secret
  2. Check credential expiration
  3. Ensure WebSocket permissions
  4. Generate new credentials if needed

WS_SUBSCRIPTION_FAILED

Description: WebSocket subscription failed.

Error Code: WS_SUBSCRIPTION_FAILED

Common Causes:

  • Invalid channel or symbol
  • Subscription limit exceeded
  • Permission denied

Example:

{
    "type": "error",
    "error": "WS_SUBSCRIPTION_FAILED",
    "message": "Failed to subscribe to channel",
    "details": {
        "channel": "ticker",
        "symbol": "INVALID/USD",
        "reason": "invalid_symbol"
    }
}

Troubleshooting:

  1. Verify channel and symbol names
  2. Check subscription limits
  3. Ensure proper permissions
  4. Review WebSocket documentation

API Error Codes

Authentication Errors

AUTH_INVALID_SIGNATURE

Description: Invalid request signature.

Error Code: AUTH_INVALID_SIGNATURE

Common Causes:

  • Incorrect secret key
  • Wrong signature algorithm
  • Timestamp issues

Troubleshooting:

  1. Verify secret key is correct
  2. Check signature generation algorithm
  3. Ensure accurate timestamp
  4. Review authentication documentation

AUTH_TIMESTAMP_TOO_OLD

Description: Request timestamp too old.

Error Code: AUTH_TIMESTAMP_TOO_OLD

Common Causes:

  • System time out of sync
  • Request delayed
  • Clock drift

Troubleshooting:

  1. Sync system time
  2. Use accurate timestamp
  3. Reduce request delay
  4. Check for clock drift

Rate Limiting Errors

RATE_LIMIT_EXCEEDED

Description: API rate limit exceeded.

Error Code: RATE_LIMIT_EXCEEDED

Common Causes:

  • Too many requests per second
  • Daily limit exceeded
  • Burst limit exceeded

Example:

{
    "error": "RATE_LIMIT_EXCEEDED",
    "message": "API rate limit exceeded",
    "code": 429,
    "details": {
        "limit_type": "requests_per_second",
        "limit": 10,
        "remaining": 0,
        "reset_time": 1640995260
    }
}

Troubleshooting:

  1. Implement request throttling
  2. Use exponential backoff
  3. Upgrade account for higher limits
  4. Use WebSocket for real-time data

Error Handling Best Practices

Client-Side Error Handling

JavaScript Example

async function handleApiRequest(url, options) {
    try {
        const response = await fetch(url, options);
        
        if (!response.ok) {
            const errorData = await response.json();
            throw new ApiError(errorData.error, errorData.message, response.status);
        }
        
        return await response.json();
    } catch (error) {
        if (error instanceof ApiError) {
            // Handle API errors
            handleApiError(error);
        } else {
            // Handle network errors
            handleNetworkError(error);
        }
    }
}

function handleApiError(error) {
    switch (error.code) {
        case 401:
            // Handle authentication error
            redirectToLogin();
            break;
        case 429:
            // Handle rate limit error
            implementBackoff();
            break;
        case 500:
            // Handle server error
            showRetryOption();
            break;
        default:
            // Handle other errors
            showGenericError(error.message);
    }
}

Python Example

import requests
from requests.exceptions import RequestException

class ApiError(Exception):
    def __init__(self, error_code, message, status_code):
        self.error_code = error_code
        self.message = message
        self.status_code = status_code
        super().__init__(self.message)

def handle_api_request(url, **kwargs):
    try:
        response = requests.get(url, **kwargs)
        response.raise_for_status()
        return response.json()
    except requests.exceptions.HTTPError as e:
        error_data = response.json()
        raise ApiError(
            error_data.get('error', 'unknown_error'),
            error_data.get('message', str(e)),
            response.status_code
        )
    except RequestException as e:
        raise ApiError('network_error', str(e), 0)

def handle_api_error(error):
    if error.status_code == 401:
        # Handle authentication error
        refresh_credentials()
    elif error.status_code == 429:
        # Handle rate limit error
        time.sleep(60)  # Wait 1 minute
    elif error.status_code == 500:
        # Handle server error
        retry_request()
    else:
        # Handle other errors
        log_error(error)

Error Recovery Strategies

Exponential Backoff

import time
import random

def exponential_backoff(attempt, base_delay=1, max_delay=60):
    delay = min(base_delay * (2 ** attempt) + random.uniform(0, 1), max_delay)
    time.sleep(delay)

def retry_with_backoff(func, max_attempts=5):
    for attempt in range(max_attempts):
        try:
            return func()
        except ApiError as e:
            if e.status_code == 429:  # Rate limit
                exponential_backoff(attempt)
            elif e.status_code >= 500:  # Server error
                exponential_backoff(attempt)
            else:
                raise  # Don't retry client errors
    raise Exception("Max retry attempts exceeded")

Circuit Breaker Pattern

class CircuitBreaker:
    def __init__(self, failure_threshold=5, timeout=60):
        self.failure_threshold = failure_threshold
        self.timeout = timeout
        self.failure_count = 0
        self.last_failure_time = None
        self.state = 'CLOSED'  # CLOSED, OPEN, HALF_OPEN
    
    def call(self, func):
        if self.state == 'OPEN':
            if time.time() - self.last_failure_time > self.timeout:
                self.state = 'HALF_OPEN'
            else:
                raise Exception("Circuit breaker is OPEN")
        
        try:
            result = func()
            if self.state == 'HALF_OPEN':
                self.state = 'CLOSED'
                self.failure_count = 0
            return result
        except Exception as e:
            self.failure_count += 1
            self.last_failure_time = time.time()
            
            if self.failure_count >= self.failure_threshold:
                self.state = 'OPEN'
            
            raise e

Troubleshooting Checklist

General Troubleshooting Steps

  1. Check Error Code: Identify the specific error code
  2. Read Error Message: Understand what went wrong
  3. Review Documentation: Check relevant documentation
  4. Verify Parameters: Ensure all parameters are correct
  5. Check Permissions: Verify account and API permissions
  6. Test with Simple Request: Try a basic request first
  7. Contact Support: If issue persists, contact support

Common Solutions

  • Authentication Issues: Regenerate API keys
  • Rate Limiting: Implement backoff strategy
  • Invalid Parameters: Check parameter format and values
  • Network Issues: Check connectivity and firewall
  • Server Errors: Retry after delay
  • Permission Issues: Upgrade account or check permissions

Need help with performance issues? Check out our Performance Issues guide.