Error Codes

Understanding and handling API errors in PaperExchange API v1.0.

Error Response Format

All errors return a JSON response with a detail field:

{
  "detail": "Error message describing what went wrong"
}

HTTP Status Codes

200OK

Request successful. Response body contains the requested data.

400Bad Request

Invalid request format or parameters. Check your request body and parameters.

401Unauthorized

Missing or invalid authentication. Check your API key or JWT token.

403Forbidden

Valid authentication but insufficient permissions. Usually means subscription expired.

404Not Found

Resource not found. Check the endpoint URL or resource ID.

429Too Many Requests

Rate limit exceeded. Wait and retry. Check X-RateLimit-Reset header.

500Internal Server Error

Server error. Please retry or contact support if the issue persists.

Common Error Messages

Error Message	Cause	Solution
`API key required`	Missing X-API-Key header	Add API key to request headers
`Invalid or revoked API key`	API key doesn't exist or was revoked	Create a new API key in dashboard
`Trial expired`	3-day trial period ended	Subscribe to continue using the API
`Subscription expired`	Monthly subscription ended	Renew subscription in billing page
`Insufficient balance`	Not enough margin for order	Reduce order size or add funds
`Invalid order parameters`	Order size/price invalid	Check size decimals and price format
`Order not found`	Order ID doesn't exist	Verify order ID from openOrders
`Position would exceed max leverage`	Order would exceed 50x leverage	Reduce position size or add margin
`Balance too high for reset`	Balance must be below $100	Reset only available when balance < $100

Error Handling Best Practices

Python Example

import requests

def make_request(endpoint, data):
    try:
        response = requests.post(
            f"https://api.paperx.co{endpoint}",
            headers={"X-API-Key": API_KEY},
            json=data
        )
        
        # Check for rate limiting
        if response.status_code == 429:
            reset_time = response.headers.get("X-RateLimit-Reset")
            print(f"Rate limited. Reset at: {reset_time}")
            return None
        
        # Check for auth errors
        if response.status_code == 401:
            print("Authentication failed. Check your API key.")
            return None
        
        if response.status_code == 403:
            print("Subscription expired. Please renew.")
            return None
        
        # Check for success
        if response.status_code == 200:
            return response.json()
        
        # Handle other errors
        error = response.json().get("detail", "Unknown error")
        print(f"Error: {error}")
        return None
        
    except requests.exceptions.RequestException as e:
        print(f"Network error: {e}")
        return None

JavaScript/TypeScript Example

async function makeRequest(endpoint, data) {
  try {
    const response = await fetch("https://api.paperx.co" + endpoint, {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "X-API-Key": API_KEY
      },
      body: JSON.stringify(data)
    });
    
    // Check for rate limiting
    if (response.status === 429) {
      const resetTime = response.headers.get("X-RateLimit-Reset");
      console.log(`Rate limited. Reset at: ${resetTime}`);
      return null;
    }
    
    // Check for auth errors
    if (response.status === 401) {
      console.log("Authentication failed. Check your API key.");
      return null;
    }
    
    if (response.status === 403) {
      console.log("Subscription expired. Please renew.");
      return null;
    }
    
    // Parse response
    const result = await response.json();
    
    if (!response.ok) {
      console.log(`Error: ${result.detail}`);
      return null;
    }
    
    return result;
    
  } catch (error) {
    console.log(`Network error: ${error.message}`);
    return null;
  }
}

Retry Strategy

For transient errors (5xx, network issues), implement exponential backoff:

First retry: Wait 1 second
Second retry: Wait 2 seconds
Third retry: Wait 4 seconds
Maximum 3 retries, then fail

Do not retry 4xx errors (except 429) - these indicate client-side issues that need to be fixed.

Next: Code Examples

See complete working examples for common trading scenarios.

View Code Examples