​

Errors

​

Quick Navigation

• HTTP Status Codes - Overview of 4xx and 5xx errors
• Specific Error Codes - Detailed list of Topsort error codes
• Debugging Tips - How to troubleshoot effectively

​

How Errors Work

​

Error Codes and Meanings

​

Error Codes

​

Debugging Tips

​

Getting More Error Details

{
  "error": "validation_error",
  "message": "Invalid request body",
  "details": [
    {
      "field": "events[0].productId",
      "message": "Product 'sku_999' not found in catalog"
    },
    {
      "field": "events[0].occurredAt", 
      "message": "Timestamp cannot be in the future"
    }
  ]
}

​

Common Integration Issues

• Check occurredAt is within last 30 days
• Verify product exists in catalog
• Confirm event type is spelled correctly (click, not Click)

• Verify active campaigns exist
• Check campaign has budget remaining (most common issue)
• Verify account balance is positive
• Confirm products are in stock and active
• Check bid amounts aren’t too low

• See our Attribution Troubleshooting Guide for detailed debugging steps

​

Using Developer Logs for Debugging

​

Handling rate limiting

​

Retry with exponential back-off

def exponential_backoff_retry(url, max_retries=5, base_delay=1, max_delay=64, retry_on_status=429):
    retries = 0
    delay = base_delay
    while retries < max_retries:
        try:
            response = requests.get(url)
            if response.status_code == retry_on_status:
                print(f"Received status code {retry_on_status}, retrying...")
                retries += 1
                if retries < max_retries:
                    print(f"Retrying in {delay} seconds...")
                    time.sleep(delay)
                    delay = min(delay * 2, max_delay)
                else:
                    raise Exception(f"All retries exhausted for status code {retry_on_status}")
            else:
                response.raise_for_status()  # Raise an exception for HTTP errors other than the specified one
                return response.json()  # Assuming the response is JSON, adjust as needed
        except Exception as e:
            print(f"Attempt {retries + 1}/{max_retries} failed: {e}")
            retries += 1
            if retries < max_retries:
                print(f"Retrying in {delay} seconds...")
                time.sleep(delay)
                delay = min(delay * 2, max_delay)
            else:
                raise

​

Use Retry-After

• X-RateLimit-Limit: how many requests you have made during the time period
• X-RateLimit-Remaining: remaining request during the time period
• X-RateLimit-Reset: when you can make another request

​

Connection and Network Issues

​

Connection Refused/Timeout Errors

• Connection refused or Connection timeout errors
• Requests hanging indefinitely
• Intermittent connectivity issues

​

Network Connectivity

• Check internet connection and DNS resolution
• Test with curl: curl -I https://api.topsort.com
• Verify API endpoint URLs are correct

​

Firewall/Proxy Issues

• Whitelist Topsort domains:
  • api.topsort.com
  • *.topsort.com
• Allow outbound HTTPS (port 443) traffic
• Configure proxy settings if your network requires them

​

SSL/TLS Certificate Problems

• Update your HTTP client to support modern TLS versions
• Check certificate validation - ensure your system trusts standard CAs
• Test with OpenSSL: openssl s_client -connect api.topsort.com:443

​

Request Timeout Issues

• Increase timeout values in your HTTP client
• Implement retry logic with exponential backoff
• Check for large request payloads that might exceed limits

# Example: Proper timeout and retry configuration
import requests
from requests.adapters import HTTPAdapter
from urllib3.util.retry import Retry

def create_topsort_session():
    session = requests.Session()
    
    # Retry strategy
    retry_strategy = Retry(
        total=3,
        backoff_factor=1,
        status_forcelist=[429, 500, 502, 503, 504],
    )
    
    # Mount adapter with retry strategy
    adapter = HTTPAdapter(max_retries=retry_strategy)
    session.mount("https://", adapter)
    
    # Set reasonable timeouts
    session.timeout = (10, 30)  # (connect, read)
    
    return session

​

Regional Connectivity Issues

• Test from different locations to isolate regional problems
• Use a CDN or proxy service if needed for your region
• Contact support with your location details for assistance

​

Basic Connectivity Test

# Test if you can reach the API domain
curl -I https://api.topsort.com

# Or test with a simple API call (requires API key)
curl -X GET "https://api.topsort.com/v2/auctions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

​

Troubleshooting Checklist

1. Test basic connectivity: Can you reach api.topsort.com?
2. Check firewall rules: Are outbound HTTPS requests allowed?
3. Verify API endpoint: Are you using the correct URL?
4. Test with minimal request: Does a simple connectivity test work?
5. Check our status page: topsort.statuspage.io
6. Review proxy settings: Are corporate proxies interfering?
7. Update TLS support: Is your client using modern TLS versions?

​

Need More Help?

• Check our status page at topsort.statuspage.io for service updates
• Contact support with your error details and API request for faster resolution
• Review our API documentation for endpoint-specific requirements and examples