错误与速率限制
无论调用哪个产品,Watch-IP 的每个端点都会以相同的结构返回错误,并以相同的方式执行速率限制。
错误响应结构
非 2xx 响应始终是一个 JSON 对象,包含 error(稳定的、可供程序判断的代码)与 message(供人阅读的描述)。error 在不同 API 版本之间保持不变;message 的文本内容可能会发生变化,因此请依据 error 进行匹配,而不是 message。
错误响应
{
"error": "invalid_ip",
"message": "\"999.999.999.999\" is not a valid IPv4 or IPv6 address."
}常见状态码
端点具体能够返回的状态码集合会记录在其各自的参考页面中;以下是整个 API 共享的通用状态码。
- 400
- 输入格式错误——无效的 IP 地址、空批次或超量批次(POST /v1/lookup 最多允许 100 个 IP),或缺少必填字段。
- 401
- API 密钥缺失或无效。
- 403
- 该路由使用了错误的密钥类型(在私密密钥端点上使用了公开可用密钥,或反之),或者——仅针对 GET /v1/geo 与 POST /v1/email/validate——Origin/Referer 不在该密钥的允许来源列表中。在来源不匹配的情况下,系统也不会设置 CORS 请求头,因此无论该响应体内容如何,浏览器都会拦截该响应。
- 422
- 语义有效但无法处理的输入——目前仅出现在 POST /v1/risk/check 中,当所提供的 IP 无法解析出位置时。
- 429
- 当前一分钟窗口内的速率限制已超出。
速率限制
速率限制按客户账户在固定的一分钟窗口内执行,该限制在您调用的所有端点之间共享,而不是按路由单独统计。该限制按 HTTP 调用次数计算，而不是按条目计算：无论包含 1 个还是 100 个条目，POST /v1/lookup 和 POST /v1/email/batch 都只算一次请求；创建、轮询和下载邮箱列表任务也是如此。因速率限制返回的 429（error: "rate_limit_exceeded"）带有 Retry-After 响应头，告知距当前窗口重置还有多少秒——等待该时长后再重试。
安全重试
GET /v1/geo、GET /v1/lookup/{ip}、POST /v1/lookup 与 POST /v1/email/validate 都是只读操作,在发生网络错误后可以立即安全重试。POST /v1/risk/check 默认会更新存储的基线位置——如果您需要一次不应影响该基线的试探性重试,请先传入 commit:false。