Zum Hauptinhalt springen
Diese Seite beschreibt Fehler, die bei der Verwendung der /auctions und /events Endpoints von Topsort oder der APIs auftreten, kategorisiert nach HTTP-Statuscode: 4xx: Anfrageproblem 5xx: Topsort-Serviceproblem Beide Fehlertypen geben JSON-Arrays mit Fehlerobjekten zurück, die folgende Felder enthalten: errCode, docUrl und eine optional message.
FeldTypBeschreibung
errCodestringEine kurze Zeichenfolge, die das Problem eindeutig identifiziert.
docUrlstringEin Link zu dieser Dokumentation mit weiteren Informationen über den Fehler.
messagestringOptional. Falls vorhanden, eine lesbare Erklärung oder Details zum Fehler. Die Zeichenfolge für einen bestimmten Fehler kann sich im Laufe der Zeit ändern; Code sollte nicht auf bestimmte Werte für dieses Feld parsen oder verzweigen.
Fehlercodes und Bedeutungen:
CodeBeschreibungDetails
400Bad RequestInakzeptable Anfrage, d.h. falsche Formatierung
403Forbidden/UnauthorizedAPI-Schlüssel-Problem oder fehlende Tokens
404Not FoundDer Server kann die angeforderte Ressource nicht finden. Entweder ist die Anfrage-URL nicht in unseren Routen vorhanden, oder die Ressource ist nicht verfügbar (z.B. die angeforderte Kampagne existiert nicht)
422Unprocessable EntityAnfrage-Body und Modell stimmen nicht überein, d.h. Ihnen fehlt eine Eigenschaft, oder die API erwartet ein Datum, hat aber eine Zahl erhalten
429Rate Limit überschrittenIP-basiertes Rate Limit erreicht. Dieser Fehler wird von den folgenden Headern begleitet:
- X-RateLimit-Limit: Gesamtzahl der zulässigen Anfragen für den Zeitraum
- X-RateLimit-Remaining: Anzahl der verbleibenden Anfragen für den Zeitraum
- X-RateLimit-Reset: Wann Sie eine weitere Anfrage stellen können

Fehlercodes

FehlercodeBeschreibung
bad_requestDie Anfrage konnte nicht geparst werden; überprüfen Sie die OpenAPI-Spezifikation für das korrekte Schema.
empty_requestDie Anfrage ist leer; überprüfen Sie die OpenAPI-Spezifikation für das korrekte Schema.
internal_server_errorUnerwartetes Serverproblem; unser Team löst diese Probleme in der Regel schnell.
invalid_api_keyAPI-Schlüssel fehlt, ist ungültig oder abgelaufen; siehe Authentifizierung für Details.
invalid_auction_idDie Auktions-ID entspricht keiner Auktion; stellen Sie sicher, dass eine gültige Auktions-ID in der Anfrage übergeben wird.
invalid_event_typeDer Ereignistyp muss “Impression”, “Click” oder “Purchase” sein.
invalid_promotion_typeUngültige Promotion-Typen im Slots-Feld.
invalid_sessionDas Session-Objekt muss eine nicht-leere sessionId enthalten.
missing_aspect_ratioDas erforderliche Seitenverhältnis für Banner-Anzeigen fehlt.
missing_auctionsMindestens eine Auktion muss angegeben werden.
missing_contextErforderlicher Kontext fehlt; geben Sie eine Kategorie, Produktliste oder Suchanfrage an.
missing_placementDas erforderliche Feld placement oder placement.page fehlt.
missing_product_idproductId fehlt.
missing_promotion_typeEine Auktion muss Slots für mindestens einen Promotion-Typ anfordern.
missing_purchased_atDas erforderliche Feld purchasedAt fehlt.
missing_sessionDas erforderliche Feld session fehlt.
missing_slotsDas erforderliche Feld slots fehlt.
no_productsMindestens ein Produkt muss angegeben werden.
no_purchase_itemsMindestens ein Artikel muss gekauft werden.
purchase_item_quantity_less_or_equal_than_zeroEin gekaufter Artikel hat eine Menge kleiner oder gleich null.
resolved_bid_id_not_foundDie angegebene aufgelöste Gebots-ID entspricht keinem internen Datensatz.
too_few_impressionsMindestens eine Impression muss enthalten sein.
too_few_slotsMindestens ein Slot muss in einer Auktion angegeben werden.
too_many_auctionsMaximal 5 Auktionen können parallel durchgeführt werden; kontaktieren Sie Ihren KAM, um dieses Limit zu erhöhen.

Umgang mit Rate Limiting

Unsere Endpoints - außer für Aufrufe von /auctions oder /events - sind rate-limited, um Missbrauch zu vermeiden. Wenn Sie das Rate Limit überschreiten, erhalten Sie eine 429 Fehlerantwort. Es gibt zwei empfohlene Methoden, um mit diesen Limits umzugehen.

Retry mit exponentiellem Backoff

Retry mit exponentiellem Backoff ist eine Technik in der Programmierung, um eine Operation mit zunehmenden Intervallen zwischen den Versuchen zu wiederholen, was hilft, Probleme wie Netzwerklatenz, vorübergehende Ausfälle oder Ressourcenbeschränkungen zu mildern. Unten ist ein Beispielcode in Python, wie die Technik implementiert werden kann.
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

Verwendung von Retry-After

Verwenden Sie die Werte in den Headern, um zu bestimmen, wann Sie eine weitere Anfrage stellen können:
  • X-RateLimit-Limit: Wie viele Anfragen Sie während des Zeitraums gestellt haben
  • X-RateLimit-Remaining: Verbleibende Anfragen während des Zeitraums
  • X-RateLimit-Reset: Wann Sie eine weitere Anfrage stellen können
Beachten Sie, dass wenn Sie verteilte Services haben, die auf die Ressource zugreifen, Sie möglicherweise immer noch 429 erhalten, selbst wenn Sie die in X-RateLimit-Reset angegebene Zeit gewartet haben. Wenn Sie auf dieses Problem stoßen, möchten Sie möglicherweise entweder diese Technik durch exponentiellen Backoff ersetzen oder beide zusammen verwenden, d.h. zuerst auf die von X-RateLimit-Reset angegebene Zeit warten und dann auf exponentiellen Backoff zurückgreifen.