Zum Hauptinhalt springen

​
Fehler

Bei der Arbeit mit Topsort-APIs können verschiedene Fehlerantworten auftreten. Dieser Leitfaden hilft Ihnen, häufige Probleme zu verstehen, zu diagnostizieren und zu beheben.

​
Fehlerantwortformat

Topsort-APIs geben Fehler als JSON-Arrays zurück, die Fehlerobjekte enthalten:
FeldTypBeschreibung
errCodestringKurze Zeichenfolge, die das Problem eindeutig identifiziert
docUrlstringLink zur Dokumentation mit weiteren Informationen
messagestringOptionale menschenlesbare Erklärung (kann sich im Laufe der Zeit ändern)

​
HTTP-Statuscodes

400 - Bad Request

Inakzeptables Anforderungsformat oder falsche Syntax. Überprüfen Sie die Anforderungsstruktur anhand der API-Spezifikation.

403 - Forbidden

API-Schlüsselproblem oder fehlende Autorisierungstoken. Überprüfen Sie Ihre Authentifizierungsdaten.

404 - Not Found

Ressource existiert nicht oder URL ist falsch. Überprüfen Sie den Endpunktpfad und die Ressourcen-ID.

422 - Unprocessable Entity

Anforderungstext entspricht nicht dem erwarteten Modell. Erforderliche Felder fehlen oder falsche Datentypen.

429 - Rate Limit

Zu viele Anfragen. Überprüfen Sie die Rate-Limit-Header: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.

5xx - Server Error

Unerwartetes Serverproblem. Unser Team behebt diese Probleme normalerweise schnell. Überprüfen Sie die Statusseite.

​
Spezifische Fehlercodes

  • invalid_api_key - Der API-Schlüssel im Autorisierungsheader fehlt, ist ungültig oder abgelaufen. Siehe Authentifizierung für Details.
  • bad_request - Die Anforderung konnte nicht geparst werden
  • invalid_json - Die Anforderung ist kein gültiges JSON
  • empty_request - Anforderungstext ist leer; stellen Sie sicher, dass Sie Daten senden
  • request_canceled - Der Aufrufer hat die Anforderung abgebrochen
  • invalid_operation - Die Operation ist im aktuellen Zustand nicht gültig
  • missing_auctions - Sie müssen mindestens eine Auktion angeben
  • too_many_auctions - Höchstens 5 Auktionen können parallel ausgeführt werden
  • too_few_slots - Mindestens ein Slot muss in einer Auktion angegeben werden
  • missing_slots - Erforderliches Slots-Feld fehlt
  • invalid_auction_id - Auktions-ID entspricht keiner gültigen Auktion
  • missing_promotion_type - Muss Slots für mindestens einen Promotion-Typ anfordern
  • invalid_promotion_type - Ungültige Promotion-Typen im Slots-Feld
  • invalid_context - Ungültiger Kontext. Muss höchstens zwei von folgenden angeben: Produktliste, Suchanfrage oder Kategorien (für Sponsored Brands: höchstens eine)
  • invalid_placement_id - Platzierungs-ID muss zwischen 1 und 8 liegen
  • missing_slot_id - Fehlende erforderliche Slot-ID für Banner-Anzeigen
  • invalid_category - Nur eines von id, ids oder disjunctions muss gesetzt sein, wobei kein Array länger als 5 ist
  • invalid_opaque_user_id - Wert der undurchsichtigen Benutzer-ID darf nicht länger als 90 Zeichen sein
  • no_products - Mindestens ein Produkt muss angegeben werden
  • no_products_or_category - Entweder mindestens eine Produkt-ID oder eine Kategorie-ID muss angegeben werden
  • too_many_products - Limit der Produkte in der Anforderung überschritten
  • product_info_mismatch - Produktinformations-Arrays müssen alle die gleiche Länge haben
  • invalid_quality_score - Qualitätswerte müssen zwischen 0.0 und 1.0 liegen
  • non_positive_price - Produktpreis muss positiv sein
  • invalid_geo_targeting - Ungültiges Geo-Targeting. Muss entweder location oder locations angeben
  • too_many_locations - Höchstens 2 Standorte können angegeben werden
  • invalid_location_cell - Angegebene Standortzelle ist keine gültige H3-Zelle
  • invalid_device - Das Gerät muss eines von sein: desktop oder mobile
  • too_many_search_query_words - Limit der Suchanfragewörter in der Anforderung überschritten
  • invalid_event_time - Mindestens ein Event liegt in der Zukunft
  • invalid_resolved_bid_id - Ungültige resolvedBidId
  • invalid_use_of_external_campaign_id - Kann nicht sowohl resolvedBidId als auch externalCampaignId setzen
  • no_purchase_items - Mindestens ein Artikel muss gekauft werden
  • missing_purchased_at - Erforderliches purchasedAt-Feld fehlt
  • invalid_marketplace - Kein solcher Marketplace existiert
  • invalid_vendor - Kein solcher Anbieter existiert
  • resource_not_found - Die angeforderte Ressource wurde nicht gefunden
  • experiment_variant_too_long - Marketplace-Experimentvarianten haben eine maximale Länge von 10 Zeichen
  • no_listing_experiment_variant - Marketplace-Experimentvarianten werden nur für Sponsored-Listing-Auktionen unterstützt
  • account_unique_violation - Anforderung verletzt eindeutige Hauptbuchkonto-Einschränkung
  • invalid_ledger_account - Hauptbuchkonto existiert nicht
  • insufficient_balance - Unzureichender Saldo
  • different_currencies - Beide Konten müssen denselben Währungscode haben
  • equal_from_and_to - From und To müssen unterschiedlich sein
  • bad_request (Filteroperation) - Die Filteroperation kann and oder or sein
  • bad_request (Attribute) - Die Anzahl der Filterattribute muss zwischen 1 und 3 liegen
  • bad_request (Promotions) - Die Anzahl der Filter-Promotions muss zwischen 1 und 3 liegen
  • invalid_travel_category - Reisekategorie muss eine nicht leere Zeichenfolge sein, wenn angegeben
  • invalid_travel_date_range - Enddatum muss größer als Startdatum sein
  • too_many_passengers - Anzahl der Passagiere muss kleiner als zehn sein
  • invalid_traveler_type - Reisender-Typ muss einer von sein: family, group, solo, couple
  • invalid_date_format - Datum muss dem Format YYYY-MM-DD folgen (z.B. 2012-05-08)
  • invalid_travel_type - Typ muss einer von sein: hotels, flights
  • missing_variation_id - Fehlende Variations-ID
  • missing_flight_travel_context - Fehlende Felder aus Flug-Reisekontext
  • internal_server_error - Der Server hat ein Problem festgestellt
  • request_canceled - Der Aufrufer hat die Anforderung abgebrochen

​
Häufige Integrationsprobleme

Events werden nicht angezeigt

Events geben 200 zurück, erscheinen aber nicht im Dashboard:
  • Überprüfen Sie, dass occurredAt innerhalb der letzten 30 Tage liegt
  • Überprüfen Sie, dass das Produkt im Katalog existiert
  • Bestätigen Sie die Schreibweise des Event-Typs (click, nicht Click)

Leere Auktionsergebnisse

Auktionen geben keine Gewinner zurück:
  • Überprüfen Sie das Kampagnenbudget (häufigstes Problem)
  • Überprüfen Sie, dass der Kontostand positiv ist
  • Bestätigen Sie, dass Produkte auf Lager und aktiv sind
  • Überprüfen Sie, dass aktive Kampagnen existieren
  • Überprüfen Sie, dass Gebotsbeträge nicht zu niedrig sind

Attributionsprobleme

Attribution funktioniert nicht korrekt:
  • Siehe unseren Attribution Troubleshooting Guide
  • Überprüfen Sie, dass aufgelöste Gebots-IDs korrekt übergeben werden
  • Überprüfen Sie, dass Kaufevents die richtigen Produkt-IDs enthalten

Verbindungsprobleme

Verbindung abgelehnt oder Timeout:
  • Testen Sie die Konnektivität: curl -I https://api.topsort.com
  • Überprüfen Sie, dass die Firewall ausgehendes HTTPS (Port 443) zulässt
  • Setzen Sie *.topsort.com-Domains auf die Whitelist
  • Überprüfen Sie die TLS/SSL-Zertifikatsvalidierung
Budgeterschöpfung ist die #1 Ursache für leere Auktionen. Bevor Sie komplexe Auktionsprobleme debuggen, überprüfen Sie zunächst, dass Ihre Kampagnen ausreichendes Tagesbudget und Kontostand haben. Kampagnen mit null Budget können nicht an Auktionen teilnehmen.

​
Detaillierte Validierungsfehler

Einige Endpunkte geben detaillierte Validierungsfehler mit Feldebeneninformationen zurück: 
{
  "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"
    }
  ]
}
Verwenden Sie das details-Array, um genau zu identifizieren, welche Felder Probleme haben und was korrigiert werden muss.

​
Rate Limiting

Exponential Backoff

Wiederholen Sie fehlgeschlagene Anfragen mit zunehmenden Verzögerungen zwischen Versuchen:
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)

Rate-Limit-Header verwenden

Beachten Sie die Rate-Limit-Header in Antworten:
  • X-RateLimit-Limit - Gesamtzahl erlaubter Anfragen
  • X-RateLimit-Remaining - Verbleibende Anfragen
  • X-RateLimit-Reset - Wann das Limit zurückgesetzt wird
Warten Sie bis X-RateLimit-Reset, bevor Sie es erneut versuchen.
Auktionen (/v2/auctions) und Events (/v2/events) Endpunkte sind nicht rate-limitiert. Rate Limits gelten für andere Endpunkte wie Kampagnenverwaltungs- und Reporting-APIs.

​
Verbindungs- & Netzwerkprobleme

​
Troubleshooting-Checkliste

1

Grundlegende Konnektivität testen

Überprüfen Sie, ob Sie die Topsort-API erreichen können:
curl -I https://api.topsort.com
2

Firewall-Regeln überprüfen

Stellen Sie sicher, dass ausgehender HTTPS-Verkehr (Port 443) erlaubt ist und setzen Sie auf die Whitelist:
  • api.topsort.com
  • *.topsort.com
3

TLS-Unterstützung überprüfen

Stellen Sie sicher, dass Ihr HTTP-Client moderne TLS-Versionen unterstützt:
openssl s_client -connect api.topsort.com:443
4

Timeouts konfigurieren

Setzen Sie geeignete Timeout-Werte und implementieren Sie Wiederholungslogik:
session = requests.Session()
session.timeout = (10, 30)  # (connect, read)
5

Statusseite überprüfen

Besuchen Sie topsort.statuspage.io für Servicestatus

​
Häufige Netzwerkprobleme

Symptome: Zertifikatsvalidierungsfehler, SSL-Handshake-FehlerLösungen:
  • Aktualisieren Sie Ihren HTTP-Client, um moderne TLS-Versionen zu unterstützen
  • Stellen Sie sicher, dass Ihr System Standard-Zertifizierungsstellen vertraut
  • Testen Sie mit: openssl s_client -connect api.topsort.com:443
Symptome: Verbindung abgelehnt, Anfragen hängenLösungen:
  • Setzen Sie Topsort-Domains auf die Whitelist (api.topsort.com, *.topsort.com)
  • Erlauben Sie ausgehenden HTTPS-Verkehr auf Port 443
  • Konfigurieren Sie Proxy-Einstellungen, falls von Ihrem Netzwerk erforderlich
  • Testen Sie ohne Proxy, um das Problem zu isolieren
Symptome: Anfragen laufen in Timeout, hängen auf unbestimmte ZeitLösungen:
  • Erhöhen Sie Timeout-Werte in Ihrem HTTP-Client
  • Implementieren Sie Wiederholungslogik mit exponentiellem Backoff
  • Überprüfen Sie auf große Anforderungsnutzlasten, die Limits überschreiten
  • Verwenden Sie Connection Pooling für bessere Leistung
Symptome: Probleme aus bestimmten geografischen RegionenLösungen:
  • Testen Sie von verschiedenen Standorten aus, um regionale Probleme zu isolieren
  • Verwenden Sie einen CDN- oder Proxy-Service bei Bedarf
  • Kontaktieren Sie den Support mit Ihren Standortdetails

​
Debugging-Tools

Entwicklerprotokolle

Überprüfen Sie die Dev Tools-Registerkarte in Ihrer Ad Platform für detaillierte API-Anforderungs-/Antwortprotokolle.Siehe unseren Entwicklerprotokolle-Leitfaden für Hilfe beim Interpretieren von Protokolleinträgen.

Statusseite

Überwachen Sie Service-Health und geplante Wartung unter topsort.statuspage.ioAbonnieren Sie Updates für Echtzeitbenachrichtigungen.

​
Benötigen Sie Hilfe?

Wenn Sie nach Konsultation dieses Leitfadens weiterhin Probleme haben:
  • Überprüfen Sie die Statusseite: topsort.statuspage.io
  • Kontaktieren Sie den Support mit Fehlerdetails und API-Anforderungsbeispielen
  • Überprüfen Sie die API-Dokumentation für endpunktspezifische Anforderungen