Skip to main content

​
Errors

When working with Topsort’s APIs, you may encounter various error responses. This guide helps you understand, diagnose, and resolve common issues.

​
Error Response Format

Topsort APIs return errors as JSON arrays containing error objects:
FieldTypeDescription
errCodestringShort string uniquely identifying the problem
docUrlstringLink to documentation providing more information
messagestringOptional human-readable explanation (may change over time)

​
HTTP Status Codes

400 - Bad Request

Unacceptable request format or incorrect syntax. Check request structure against API spec.

403 - Forbidden

API key issue or missing authorization tokens. Verify your authentication credentials.

404 - Not Found

Resource doesn’t exist or URL is incorrect. Check the endpoint path and resource ID.

422 - Unprocessable Entity

Request body doesn’t match expected model. Missing required fields or wrong data types.

429 - Rate Limit

Too many requests. Check rate limit headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.

5xx - Server Error

Unexpected server problem. Our team typically fixes these issues quickly. Check status page.

​
Specific Error Codes

  • invalid_api_key - The API key in the authorization header is missing, invalid, or has expired. See authentication for details.
  • bad_request - The request could not be parsed
  • invalid_json - The request is not valid JSON
  • empty_request - Request body is empty; ensure you’re sending data
  • request_canceled - The caller canceled the request
  • invalid_operation - The operation is not valid in the current state
  • missing_auctions - You must specify at least one auction
  • too_many_auctions - At most 5 auctions can be run in parallel
  • too_few_slots - At least one slot must be specified in an auction
  • missing_slots - Missing required slots field
  • invalid_auction_id - Auction ID doesn’t correspond to a valid auction
  • missing_promotion_type - Must request slots for at least one promotion type
  • invalid_promotion_type - Invalid promotion types in slots field
  • invalid_context - Invalid context. Must specify at most two of: list of products, search query, or categories (for sponsored brands: at most one)
  • invalid_placement_id - Placement ID must be between 1 and 8
  • missing_slot_id - Missing required slot ID for banner ads
  • invalid_category - Only one of id, ids, or disjunctions must be set, where no array is longer than 5
  • invalid_opaque_user_id - Opaque user ID value must be no longer than 90 characters
  • no_products - At least one product must be specified
  • no_products_or_category - Either at least one product ID or a category ID must be provided
  • too_many_products - Exceeded limit of products in the request
  • product_info_mismatch - Product info arrays must all have the same length
  • invalid_quality_score - Quality scores must be between 0.0 and 1.0
  • non_positive_price - Product price must be positive
  • invalid_geo_targeting - Invalid geo targeting. Must specify either location or locations
  • too_many_locations - At most 2 locations can be specified
  • invalid_location_cell - Specified location cell is not a valid H3 cell
  • invalid_device - The device must be one of: desktop or mobile
  • too_many_search_query_words - Exceeded limit of search query words in the request
  • invalid_event_time - At least one event is in the future
  • invalid_resolved_bid_id - Invalid resolvedBidId
  • invalid_use_of_external_campaign_id - Cannot set both resolvedBidId and externalCampaignId
  • no_purchase_items - At least one item must be purchased
  • missing_purchased_at - Required purchasedAt field is missing
  • invalid_marketplace - No such marketplace exists
  • invalid_vendor - No such vendor exists
  • resource_not_found - The requested resource was not found
  • experiment_variant_too_long - Marketplace experiment variants have a maximum length of 10 characters
  • no_listing_experiment_variant - Marketplace experiment variants are only supported for sponsored listing auctions
  • account_unique_violation - Request breaks ledger account unique constraint
  • invalid_ledger_account - Ledger account does not exist
  • insufficient_balance - Insufficient balance
  • different_currencies - Both accounts must have the same currency code
  • equal_from_and_to - From and to must be different
  • bad_request (filter operation) - The filter operation can be one of and or or
  • bad_request (attributes) - The number of filter attributes needs to be between 1 and 3
  • bad_request (promotions) - The number of filter promotions needs to be between 1 and 3
  • invalid_travel_category - Travel category must be a non-empty string if provided
  • invalid_travel_date_range - End date must be greater than start date
  • too_many_passengers - Number of passengers must be less than ten
  • invalid_traveler_type - Traveler type must be one of: family, group, solo, couple
  • invalid_date_format - Date must follow format YYYY-MM-DD (e.g., 2012-05-08)
  • invalid_travel_type - Type must be one of: hotels, flights
  • missing_variation_id - Missing variation ID
  • missing_flight_travel_context - Missing fields from flight travel context
  • internal_server_error - The server has encountered a problem
  • request_canceled - The caller canceled the request

​
Common Integration Issues

Events Not Appearing

Events return 200 but don’t show in dashboard:
  • Check occurredAt is within last 30 days
  • Verify product exists in catalog
  • Confirm event type spelling (click, not Click)

Empty Auction Results

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

Attribution Issues

Attribution not working correctly:

Connection Problems

Connection refused or timeout:
  • Test connectivity: curl -I https://api.topsort.com
  • Check firewall allows outbound HTTPS (port 443)
  • Whitelist *.topsort.com domains
  • Verify TLS/SSL certificate validation
Budget exhaustion is the #1 cause of empty auctions. Before debugging complex auction issues, first check that your campaigns have sufficient daily budget and account balance. Campaigns with zero budget cannot participate in auctions.

​
Detailed Validation Errors

Some endpoints return detailed validation errors with field-level information: 
{
  "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"
    }
  ]
}
Use the details array to identify exactly which fields have issues and what needs to be corrected.

​
Rate Limiting

Exponential Backoff

Retry failed requests with increasing delays between attempts:
def retry_with_backoff(url, max_retries=5):
    delay = 1
    for i in range(max_retries):
        response = requests.get(url)
        if response.status_code != 429:
            return response
        time.sleep(delay)
        delay = min(delay * 2, 64)

Use Rate Limit Headers

Respect the rate limit headers in responses:
  • X-RateLimit-Limit - Total requests allowed
  • X-RateLimit-Remaining - Requests remaining
  • X-RateLimit-Reset - When limit resets
Wait until X-RateLimit-Reset before retrying.
Auctions (/v2/auctions) and Events (/v2/events) endpoints are not rate-limited. Rate limits apply to other endpoints like campaign management and reporting APIs.

​
Connection & Network Issues

​
Troubleshooting Checklist

1

Test Basic Connectivity

Verify you can reach Topsort’s API:
curl -I https://api.topsort.com
2

Check Firewall Rules

Ensure outbound HTTPS (port 443) traffic is allowed and whitelist:
  • api.topsort.com
  • *.topsort.com
3

Verify TLS Support

Ensure your HTTP client supports modern TLS versions:
openssl s_client -connect api.topsort.com:443
4

Configure Timeouts

Set appropriate timeout values and implement retry logic:
session = requests.Session()
session.timeout = (10, 30)  # (connect, read)
5

Check Status Page

Visit topsort.statuspage.io for service status

​
Common Network Issues

Symptoms: Certificate validation errors, SSL handshake failuresSolutions:
  • Update your HTTP client to support modern TLS versions
  • Ensure your system trusts standard certificate authorities
  • Test with: openssl s_client -connect api.topsort.com:443
Symptoms: Connection refused, requests hangingSolutions:
  • Whitelist Topsort domains (api.topsort.com, *.topsort.com)
  • Allow outbound HTTPS traffic on port 443
  • Configure proxy settings if required by your network
  • Test without proxy to isolate issue
Symptoms: Requests timing out, hanging indefinitelySolutions:
  • Increase timeout values in your HTTP client
  • Implement retry logic with exponential backoff
  • Check for large request payloads exceeding limits
  • Use connection pooling for better performance
Symptoms: Issues from specific geographic regionsSolutions:
  • Test from different locations to isolate regional problems
  • Use a CDN or proxy service if needed
  • Contact support with your location details

​
Debugging Tools

Developer Logs

Check the Dev Tools tab in your Ad Platform for detailed API request/response logs.See our Developer Logs guide for help interpreting log entries.

Status Page

Monitor service health and planned maintenance at topsort.statuspage.ioSubscribe to updates for real-time notifications.

​
Need Help?

If you’re still experiencing issues after consulting this guide:
  • Check status page: topsort.statuspage.io
  • Contact support with error details and API request examples
  • Review API docs for endpoint-specific requirements