/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.
| Feld | Typ | Beschreibung |
|---|---|---|
| errCode | string | Eine kurze Zeichenfolge, die das Problem eindeutig identifiziert. |
| docUrl | string | Ein Link zu dieser Dokumentation mit weiteren Informationen über den Fehler. |
| message | string | Optional. 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. |
| Code | Beschreibung | Details | ||
|---|---|---|---|---|
| 400 | Bad Request | Inakzeptable Anfrage, d.h. falsche Formatierung | ||
| 403 | Forbidden/Unauthorized | API-Schlüssel-Problem oder fehlende Tokens | ||
| 404 | Not Found | Der 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) | ||
| 422 | Unprocessable Entity | Anfrage-Body und Modell stimmen nicht überein, d.h. Ihnen fehlt eine Eigenschaft, oder die API erwartet ein Datum, hat aber eine Zahl erhalten | ||
| 429 | Rate Limit überschritten | IP-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
| Fehlercode | Beschreibung |
|---|---|
| bad_request | Die Anfrage konnte nicht geparst werden; überprüfen Sie die OpenAPI-Spezifikation für das korrekte Schema. |
| empty_request | Die Anfrage ist leer; überprüfen Sie die OpenAPI-Spezifikation für das korrekte Schema. |
| internal_server_error | Unerwartetes Serverproblem; unser Team löst diese Probleme in der Regel schnell. |
| invalid_api_key | API-Schlüssel fehlt, ist ungültig oder abgelaufen; siehe Authentifizierung für Details. |
| invalid_auction_id | Die Auktions-ID entspricht keiner Auktion; stellen Sie sicher, dass eine gültige Auktions-ID in der Anfrage übergeben wird. |
| invalid_event_type | Der Ereignistyp muss “Impression”, “Click” oder “Purchase” sein. |
| invalid_promotion_type | Ungültige Promotion-Typen im Slots-Feld. |
| invalid_session | Das Session-Objekt muss eine nicht-leere sessionId enthalten. |
| missing_aspect_ratio | Das erforderliche Seitenverhältnis für Banner-Anzeigen fehlt. |
| missing_auctions | Mindestens eine Auktion muss angegeben werden. |
| missing_context | Erforderlicher Kontext fehlt; geben Sie eine Kategorie, Produktliste oder Suchanfrage an. |
| missing_placement | Das erforderliche Feld placement oder placement.page fehlt. |
| missing_product_id | productId fehlt. |
| missing_promotion_type | Eine Auktion muss Slots für mindestens einen Promotion-Typ anfordern. |
| missing_purchased_at | Das erforderliche Feld purchasedAt fehlt. |
| missing_session | Das erforderliche Feld session fehlt. |
| missing_slots | Das erforderliche Feld slots fehlt. |
| no_products | Mindestens ein Produkt muss angegeben werden. |
| no_purchase_items | Mindestens ein Artikel muss gekauft werden. |
| purchase_item_quantity_less_or_equal_than_zero | Ein gekaufter Artikel hat eine Menge kleiner oder gleich null. |
| resolved_bid_id_not_found | Die angegebene aufgelöste Gebots-ID entspricht keinem internen Datensatz. |
| too_few_impressions | Mindestens eine Impression muss enthalten sein. |
| too_few_slots | Mindestens ein Slot muss in einer Auktion angegeben werden. |
| too_many_auctions | Maximal 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.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 habenX-RateLimit-Remaining: Verbleibende Anfragen während des ZeitraumsX-RateLimit-Reset: Wann Sie eine weitere Anfrage stellen können
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.