Fehler und Ratenbegrenzungen
Jeder Watch-IP-Endpoint liefert Fehler in derselben Form und setzt Ratenbegrenzungen auf dieselbe Weise durch, unabhängig davon, welches Produkt Sie aufrufen.
Form der Fehlerantwort
Eine Nicht-2xx-Antwort ist immer ein JSON-Objekt mit error (ein stabiler, maschinenlesbarer Code) und message (eine menschenlesbare Beschreibung). error bleibt über API-Versionen hinweg konstant; der Text von message kann sich ändern, gleichen Sie also gegen error ab, nicht gegen message.
Fehlerantwort
{
"error": "invalid_ip",
"message": "\"999.999.999.999\" is not a valid IPv4 or IPv6 address."
}Allgemeine Statuscodes
Die genaue Menge der Codes, die ein Endpoint zurückgeben kann, ist auf seiner eigenen Referenzseite dokumentiert; dies sind die über die gesamte API hinweg gemeinsamen.
- 400
- Fehlerhafte Eingabe — eine ungültige IP-Adresse, ein leerer oder zu großer Batch (POST /v1/lookup erlaubt bis zu 100 IPs) oder ein fehlendes Pflichtfeld.
- 401
- Fehlender oder ungültiger API-Schlüssel.
- 403
- Falscher Schlüsseltyp für diese Route (ein veröffentlichbarer Schlüssel bei einem Endpoint für geheime Schlüssel oder umgekehrt), oder — nur für GET /v1/geo und POST /v1/email/validate — ein Origin/Referer, der nicht in der Liste der erlaubten Origins des Schlüssels steht. In diesem Fall wird auch kein CORS-Header gesetzt, sodass der Browser die Antwort unabhängig von diesem Textkörper blockiert.
- 422
- Semantisch gültige Eingabe, die nicht verarbeitet werden kann — derzeit nur POST /v1/risk/check, wenn die angegebene IP keinem Standort zugeordnet werden kann.
- 429
- Ratenlimit für das aktuelle Ein-Minuten-Fenster überschritten.
Ratenbegrenzungen
Ratenbegrenzungen werden pro Kundenkonto in einem festen Ein-Minuten-Fenster durchgesetzt, das über alle von Ihnen aufgerufenen Endpoints geteilt wird, statt pro Route verfolgt zu werden. Die Begrenzung zählt HTTP-Aufrufe, nicht Einträge: POST /v1/lookup und POST /v1/email/batch zählen als eine Anfrage, egal ob sie 1 oder 100 Einträge enthalten, ebenso das Anlegen, Abfragen und Herunterladen eines E-Mail-Listenjobs. Ein 429 wegen der Ratenbegrenzung (error: "rate_limit_exceeded") enthält einen Retry-After-Header mit der Anzahl Sekunden bis zum Zurücksetzen des aktuellen Fensters — warten Sie so lange und versuchen Sie es dann erneut.
Sicher erneut versuchen
GET /v1/geo, GET /v1/lookup/{ip}, POST /v1/lookup und POST /v1/email/validate sind lesend und können nach einem Netzwerkfehler sofort erneut versucht werden. POST /v1/risk/check aktualisiert standardmäßig eine gespeicherte Baseline — übergeben Sie zunächst commit:false, wenn Sie einen spekulativen erneuten Versuch benötigen, der sie nicht verändern soll.