Foutmeldingen en rate limits
Elk Watch-IP-endpoint geeft foutmeldingen in dezelfde vorm terug en handhaaft rate limits op dezelfde manier, ongeacht welk product je aanroept.
Vorm van een foutantwoord
Een niet-2xx-antwoord is altijd een JSON-object met error (een stabiele, machineleesbare code) en message (een leesbare beschrijving voor mensen). error blijft constant tussen API-versies; de tekst van message kan veranderen, dus match op error, niet op message.
Foutantwoord
{
"error": "invalid_ip",
"message": "\"999.999.999.999\" is not a valid IPv4 or IPv6 address."
}Veelvoorkomende statuscodes
De exacte set codes die een endpoint kan teruggeven, staat op de bijbehorende referentiepagina; dit zijn de codes die door de hele API worden gedeeld.
- 400
- Onjuist geformatteerde invoer — een ongeldig IP-adres, een lege of te grote batch (POST /v1/lookup staat tot 100 IP's toe), of een verplicht veld dat ontbreekt.
- 401
- Ontbrekende of ongeldige API-sleutel.
- 403
- Verkeerd sleuteltype voor deze route (een publiceerbare sleutel op een endpoint voor geheime sleutels, of andersom), of — alleen voor GET /v1/geo en POST /v1/email/validate — een Origin/Referer die niet op de lijst met toegestane origins van de sleutel staat. In het geval van de origin wordt er ook geen CORS-header gezet, dus de browser blokkeert het antwoord ongeacht deze inhoud.
- 422
- Semantisch geldige invoer die niet verwerkt kan worden — momenteel alleen POST /v1/risk/check, wanneer het opgegeven IP niet naar een locatie kan worden herleid.
- 429
- Rate limit overschreden voor het huidige venster van één minuut.
Rate limits
Rate limits worden per klantaccount gehandhaafd binnen een vast venster van één minuut, gedeeld over elk endpoint dat je aanroept in plaats van per route bijgehouden. De limiet telt HTTP-aanroepen, geen items: POST /v1/lookup en POST /v1/email/batch tellen als één verzoek, of ze nu 1 of 100 items bevatten, net als het aanmaken, opvragen en downloaden van een e-maillijstjob. Een 429 door de rate limit (error: "rate_limit_exceeded") bevat een Retry-After-header met het aantal seconden tot het huidige venster wordt gereset — wacht zo lang en probeer het dan opnieuw.
Veilig opnieuw proberen
GET /v1/geo, GET /v1/lookup/{ip}, POST /v1/lookup en POST /v1/email/validate zijn alleen-lezen en veilig om direct opnieuw te proberen na een netwerkfout. POST /v1/risk/check werkt standaard een opgeslagen baseline bij — geef eerst commit:false mee als je een speculatieve nieuwe poging nodig hebt die deze niet mag verplaatsen.