Errores y límites de tasa
Todos los endpoints de Watch-IP devuelven los errores con la misma forma y aplican los límites de tasa de la misma manera, sin importar qué producto estés llamando.
Forma de la respuesta de error
Una respuesta que no sea 2xx siempre es un objeto JSON con error (un código estable y legible por máquina) y message (una descripción legible para humanos). error se mantiene constante entre versiones de la API; el texto de message puede cambiar, así que compara contra error, no contra message.
Respuesta de error
{
"error": "invalid_ip",
"message": "\"999.999.999.999\" is not a valid IPv4 or IPv6 address."
}Códigos de estado comunes
El conjunto exacto de códigos que puede devolver un endpoint está documentado en su propia página de referencia; estos son los que se comparten en toda la API.
- 400
- Entrada malformada: una dirección IP no válida, un lote vacío o demasiado grande (POST /v1/lookup permite hasta 100 IP), o un campo obligatorio faltante.
- 401
- Clave de API faltante o no válida.
- 403
- Tipo de clave incorrecto para esta ruta (una clave publicable en un endpoint de clave secreta, o viceversa), o —solo para GET /v1/geo y POST /v1/email/validate— un Origin/Referer que no está en la lista de orígenes permitidos de la clave. En el caso de origen, tampoco se configura ningún encabezado CORS, así que el navegador bloquea la respuesta sin importar este cuerpo.
- 422
- Entrada semánticamente válida que no se puede procesar; actualmente solo ocurre en POST /v1/risk/check, cuando la IP proporcionada no se puede resolver a una ubicación.
- 429
- Límite de tasa superado para la ventana de un minuto actual.
Límites de tasa
Los límites de tasa se aplican por cuenta de cliente en una ventana fija de un minuto, compartida entre todos los endpoints que llames en lugar de contabilizarse por ruta. El límite cuenta llamadas HTTP, no elementos: POST /v1/lookup y POST /v1/email/batch cuentan como una sola solicitud tanto si llevan 1 como 100 entradas, al igual que crear, consultar y descargar un trabajo de lista de correos. Un 429 por límite de tasa (error: "rate_limit_exceeded") incluye una cabecera Retry-After con los segundos que faltan para que se reinicie la ventana actual — espera ese tiempo y vuelve a intentarlo.
Reintentar de forma segura
GET /v1/geo, GET /v1/lookup/{ip}, POST /v1/lookup y POST /v1/email/validate son de solo lectura y es seguro reintentarlos inmediatamente después de un error de red. POST /v1/risk/check actualiza por defecto una línea base almacenada; envía primero commit:false si necesitas un reintento especulativo que no deba modificarla.