This page outlines errors encountered when using Topsort’s /auctions and /events endpoints or APIs, classified by HTTP status code:

4xx: Request problem
5xx: Topsort service problem

Both errors return JSON arrays containing error objects with fields: errCode, docUrl, and an optional message.

Error Codes and Meanings:

​

Error Codes

​

Handling rate limiting

Our endpoints - except making calls to /auctions or /events - are rate-limited to prevent abuse. If you exceed the rate limit, you will receive a 429 error response. There are two recommended ways to handle these limits

​

Retry with exponential back-off

Exponential backoff retry is a technique used in programming to retry an operation with increasing intervals between retries, which helps to mitigate issues such as network latency, temporary failures, or resource constraints. Below there is a code example in Python on how the technique can be implemented.

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

Use the values in the headers to determine when you can make another request:

• 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

Note that if you have distributed services hitting the resource, you can still get 429, even if you waited the time amount specified in X-RateLimit-Reset. If you are hitting this problem, you may want to either replace this technique with the Exponential back-off or use them together, that is, first waiting the amount of time given by X-RateLimit-Reset and then fall-back to exponential back-off retries.