Erreurs et limites de débit
Chaque point de terminaison Watch-IP renvoie les erreurs sous la même forme et applique les limites de débit de la même façon, quel que soit le produit appelé.
Forme de la réponse d'erreur
Une réponse non-2xx est toujours un objet JSON avec error (un code stable, lisible par une machine) et message (une description lisible par un humain). error reste constant selon les versions de l'API ; le texte de message peut changer, donc basez votre logique sur error, pas sur message.
Réponse d'erreur
{
"error": "invalid_ip",
"message": "\"999.999.999.999\" is not a valid IPv4 or IPv6 address."
}Codes de statut courants
L'ensemble exact des codes qu'un point de terminaison peut renvoyer est documenté sur sa propre page de référence ; voici ceux qui sont partagés dans toute l'API.
- 400
- Entrée malformée — une adresse IP invalide, un lot vide ou trop volumineux (POST /v1/lookup accepte jusqu'à 100 IP), ou un champ requis manquant.
- 401
- Clé API manquante ou invalide.
- 403
- Mauvais type de clé pour cette route (une clé publiable sur un point de terminaison à clé secrète, ou l'inverse), ou — pour GET /v1/geo et POST /v1/email/validate uniquement — une Origin/Referer absente de la liste des origines autorisées de la clé. Dans ce dernier cas, aucun en-tête CORS n'est défini non plus, donc le navigateur bloque la réponse quel que soit ce corps.
- 422
- Entrée sémantiquement valide mais impossible à traiter — actuellement uniquement POST /v1/risk/check, lorsque l'IP fournie ne peut pas être résolue en un lieu.
- 429
- Limite de débit dépassée pour la fenêtre d'une minute en cours.
Limites de débit
Les limites de débit sont appliquées par compte client sur une fenêtre fixe d'une minute, partagée entre tous les points de terminaison que vous appelez plutôt que suivie par route. La limite compte les appels HTTP, pas les éléments : POST /v1/lookup et POST /v1/email/batch comptent pour une seule requête, qu'ils contiennent 1 ou 100 entrées, tout comme la création, la consultation et le téléchargement d'une tâche de liste d'e-mails. Une réponse 429 due à la limite de débit (error: "rate_limit_exceeded") inclut un en-tête Retry-After indiquant le nombre de secondes avant la réinitialisation de la fenêtre en cours — attendez ce délai, puis réessayez.
Réessayer en toute sécurité
GET /v1/geo, GET /v1/lookup/{ip}, POST /v1/lookup et POST /v1/email/validate sont en lecture seule et peuvent être réessayés immédiatement après une erreur réseau. POST /v1/risk/check met à jour une base de référence stockée par défaut — passez commit:false si vous avez besoin d'un nouvel essai spéculatif qui ne doit pas la modifier.