Zum Hauptinhalt springen

​
Fehler

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

​
Fehlerantwort-Format

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 lesbare Erklärung (kann sich im Laufe der Zeit ändern)

​
HTTP-Statuscodes

400 - Fehlerhafte Anfrage

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

403 - Verboten

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

404 - Nicht Gefunden

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

422 - Nicht Verarbeitbare Entität

Der Anfragekörper 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 - Serverfehler

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

​
Spezifische Fehlercodes

invalid_api_key - API-Schlüssel fehlt, ist ungültig oder abgelaufen. Siehe Authentifizierung für Details.
  • bad_request - Anfrage konnte nicht geparst werden; überprüfen Sie die OpenAPI-Spezifikation
  • empty_request - Anfragekörper ist leer; stellen Sie sicher, dass Sie Daten senden
  • missing_auctions - Mindestens eine Auktion muss angegeben werden
  • too_many_auctions - Maximal 5 Auktionen können parallel laufen (kontaktieren Sie KAM zum Erhöhen)
  • 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
  • missing_context - Erforderlicher Kontext fehlt; geben Sie Kategorie, Produktliste oder Suchanfrage an
  • missing_placement - Erforderliches placement- oder placement.page-Feld fehlt
  • missing_session - Erforderliches session-Feld fehlt
  • invalid_session - session-Objekt muss eine nicht-leere sessionId enthalten
  • no_products - Mindestens ein Produkt muss angegeben werden
  • missing_product_id - productId-Feld fehlt
  • invalid_event_type - Ereignistyp muss “Impression”, “Click” oder “Purchase” sein
  • too_few_impressions - Mindestens eine Impression muss enthalten sein
  • missing_slot_id - Erforderliches slotId-Feld fehlt
  • resolved_bid_id_not_found - Bereitgestellte aufgelöste Gebots-ID entspricht keinem internen Datensatz
  • no_purchase_items - Mindestens ein Artikel muss gekauft werden
  • missing_purchased_at - Erforderliches purchasedAt-Feld fehlt
  • purchase_item_quantity_less_or_equal_than_zero - Kaufartikel-Menge muss größer als null sein
  • internal_server_error - Unerwartetes Serverproblem; unser Team behebt diese normalerweise schnell

​
Häufige Integrationsprobleme

Ereignisse Erscheinen Nicht

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

Leere Auktionsergebnisse

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

Attributionsprobleme

Attribution funktioniert nicht korrekt:
  • Siehe unser Attributions-Fehlerbehebungsleitfaden
  • Überprüfen Sie, ob aufgelöste Gebots-IDs korrekt übergeben werden
  • Überprüfen Sie, ob Kaufereignisse die richtigen Produkt-IDs enthalten

Verbindungsprobleme

Verbindung abgelehnt oder Zeitüberschreitung:
  • Testen Sie die Konnektivität: curl -I https://api.topsort.com
  • Überprüfen Sie, ob die Firewall ausgehendes HTTPS (Port 443) erlaubt
  • Setzen Sie *.topsort.com-Domains auf die Whitelist
  • Überprüfen Sie die TLS/SSL-Zertifikatvalidierung
Budgeterschöpfung ist die Ursache Nr. 1 für leere Auktionen. Bevor Sie komplexe Auktionsprobleme debuggen, überprüfen Sie zuerst, ob Ihre Kampagnen ausreichendes Tagesbudget und Kontoguthaben haben. Kampagnen mit Null-Budget können nicht an Auktionen teilnehmen.

​
Detaillierte Validierungsfehler

Einige Endpoints geben detaillierte Validierungsfehler mit Informationen auf Feldebene 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

Exponentieller Backoff

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

Respektieren Sie die Rate-Limit-Header in den Antworten:
  • X-RateLimit-Limit - Gesamtzahl zulässiger 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.
Auktions- (/v2/auctions) und Ereignis- (/v2/events) Endpoints sind nicht rate-limited. Rate Limits gelten für andere Endpoints wie Kampagnenverwaltungs- und Reporting-APIs.

​
Verbindungs- und Netzwerkprobleme

​
Fehlerbehebungs-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

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

Statusseite Überprüfen

Besuchen Sie topsort.statuspage.io für den Servicestatus

​
Häufige Netzwerkprobleme

Symptome: Zertifikatvalidierungsfehler, SSL-Handshake-FehlerLösungen:
  • Aktualisieren Sie Ihren HTTP-Client zur Unterstützung moderner TLS-Versionen
  • Stellen Sie sicher, dass Ihr System Standard-Zertifizierungsstellen vertraut
  • Testen Sie mit: openssl s_client -connect api.topsort.com:443
Symptome: Verbindung abgelehnt, hängende AnfragenLö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 mit Zeitüberschreitung, hängen auf unbestimmte ZeitLösungen:
  • Erhöhen Sie die Timeout-Werte in Ihrem HTTP-Client
  • Implementieren Sie Wiederholungslogik mit exponentiellem Backoff
  • Überprüfen Sie auf große Anfrage-Payloads, die Limits überschreiten
  • Verwenden Sie Connection Pooling für bessere Leistung
Symptome: Probleme aus bestimmten geografischen RegionenLösungen:
  • Testen Sie von verschiedenen Standorten, um regionale Probleme zu isolieren
  • Verwenden Sie bei Bedarf einen CDN- oder Proxy-Service
  • 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-Request/Response-Protokolle.Siehe unseren Entwicklerprotokolle-Leitfaden für Hilfe beim Interpretieren von Protokolleinträgen.

Statusseite

Überwachen Sie Servicezustand und geplante Wartung auf topsort.statuspage.ioAbonnieren Sie Updates für Echtzeitbenachrichtigungen.

​
Brauchen Sie Hilfe?

Wenn Sie nach der Konsultation dieses Leitfadens immer noch Probleme haben:
  • Überprüfen Sie die Statusseite: topsort.statuspage.io
  • Kontaktieren Sie den Support mit Fehlerdetails und API-Anfragebeispielen
  • Überprüfen Sie die API-Dokumentation für endpoint-spezifische Anforderungen
Last updated: