Watch-IP

Errori e limiti di frequenza

Ogni endpoint di Watch-IP restituisce gli errori nello stesso formato e applica i limiti di frequenza allo stesso modo, indipendentemente dal prodotto che stai chiamando.

Formato della risposta di errore

Una risposta non-2xx è sempre un oggetto JSON con error (un codice stabile e leggibile da una macchina) e message (una descrizione leggibile da una persona). error resta costante tra le versioni dell'API; il testo di message può cambiare, quindi verifica error, non message.

Risposta di errore

{
  "error": "invalid_ip",
  "message": "\"999.999.999.999\" is not a valid IPv4 or IPv6 address."
}

Codici di stato comuni

L'insieme esatto dei codici che un endpoint può restituire è documentato nella sua pagina di riferimento; questi sono quelli condivisi da tutta l'API.

400
Input malformato — un indirizzo IP non valido, un batch vuoto o troppo grande (POST /v1/lookup consente fino a 100 IP), oppure un campo obbligatorio mancante.
401
Chiave API mancante o non valida.
403
Tipo di chiave errato per questa rotta (una chiave pubblicabile su un endpoint che richiede una chiave segreta, o viceversa), oppure — solo per GET /v1/geo e POST /v1/email/validate — un'Origin/Referer non presente nell'elenco di origini consentite della chiave. In quest'ultimo caso non viene impostato nemmeno alcun header CORS, quindi il browser blocca la risposta indipendentemente da questo corpo.
422
Input semanticamente valido ma non elaborabile — attualmente solo su POST /v1/risk/check, quando l'IP fornito non può essere risolto in una posizione.
429
Limite di frequenza superato per l'attuale finestra di un minuto.

Limiti di frequenza

I limiti di frequenza sono applicati per account cliente su una finestra fissa di un minuto, condivisa tra tutti gli endpoint che chiami, non tracciata per singola rotta. Il limite conta le chiamate HTTP, non gli elementi: POST /v1/lookup e POST /v1/email/batch contano come una sola richiesta sia che contengano 1 sia 100 voci, così come creare, interrogare e scaricare un job di lista email. Un 429 dovuto al limite di frequenza (error: "rate_limit_exceeded") include un header Retry-After con il numero di secondi mancanti al reset della finestra corrente — attendi quel tempo, poi riprova.

Riprovare in sicurezza

GET /v1/geo, GET /v1/lookup/{ip}, POST /v1/lookup e POST /v1/email/validate sono di sola lettura e possono essere ritentati immediatamente dopo un errore di rete. POST /v1/risk/check aggiorna per impostazione predefinita una baseline memorizzata — passa prima commit:false se ti serve un tentativo speculativo che non deve modificarla.

Pagine correlate