适用场景与核心价值
浏览器指纹风控API通过对20+维度的浏览器环境数据进行综合评分（0-100），识别爬虫、Headless Chrome、Selenium、虚拟机等异常客户端。在账户准备、登录、下单、票务抢购等场景中，可作为风险预判的依据。
但任何API都有其调用边界：每秒查询率（QPS）限制、请求体最大体积、字段完整性要求、返回超时约定等。本次文章将围绕这些边界展开，帮助你在设计系统时提前规避“触限”风险。
接口能力边界
1. QPS限制：5次/秒
根据API事实卡，该接口的QPS为 5/s。这意味着在一个时间窗口（1秒）内，从同一凭证（API Key）发出的请求不应超过5次。超出后API将返回错误码（通常是 429 Too Many Requests 或自定义 code）。
典型影响场景：
- 高并发准备/登录入口：如果瞬时流量超过5 QPS，需要对请求进行排队或降级。
- 批量离线分析（如历史数据重跑）：建议控制并发数，或使用令牌桶/漏桶算法平滑请求。
注意：QPS 限制是基于账户维度的，还是基于 IP 维度的？素材未明确，建议以官方文档或技术支持回复为准。设计时最好预留 20% 的余量，即实际控制在 4 QPS 以内。
2. 请求体大小与字段约束
接口要求 Content-Type: application/json，请求体是一个 JSON 对象。虽然素材未给出最大 body 大小，但通常JSON API 限制在 1MB 以内。需要特别注意的是：
- 必填字段：
ua（user agent）是唯一必填项。 - 可选字段：platform、language、timezone、timezoneOffset、screenWidth、screenHeight、colorDepth、pixelRatio、hardwareConcurrency 等。
- 如果客户端无法采集某些字段，可以留空或缺省，API仍会基于已有数据评分。但建议尽可能提供完整数据，以提高风险识别的精度。
3. 响应超时与服务稳定性
生产环境建议设置请求超时时间为 5-10 秒（考虑网络延迟和API处理时间）。若连续超时，应触发降级策略（如放行或读取本地缓存评分）。
请求参数与鉴权
Header 参数
| 参数 | 是否必填 | 类型 | 说明 |
|---|---|---|---|
| Authorization | 否 | string | 部分版本使用 X-API-Key 或 Authorization；素材中的 curl 示例使用了X-API-Key，建议两种都测试并以文档为准 |
| Content-Type | 是 | string | 固定 application/json |
鉴权方式：通过 API Key 进行身份验证。通常在请求头中携带X-API-Key: your_api_key。
请求体字段详解
| 字段名 | 类型 | 必填 | 描述 | 示例 |
|---|---|---|---|---|
| ua | string | 是 | navigator.userAgent | "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36..." |
| platform | string | 否 | navigator.platform | "Win32" |
| language | string | 否 | 主语言 | "zh-CN" |
| timezone | string | 否 | IANA 时区 | "Asia/Shanghai" |
| timezoneOffset | number | 否 | getTimezoneOffset()，分钟 | -480 |
| screenWidth | number | 否 | screen.width | 1920 |
| screenHeight | number | 否 | screen.height | 1080 |
| colorDepth | number | 否 | screen.colorDepth | 24 |
| pixelRatio | number | 否 | devicePixelRatio | 1.5 |
| hardwareConcurrency | number | 否 | navigator.hardwareConcurrency | 8 |
完整字段列表请参考官方文档（约20+维度）。
curl 请求示例
以下是一个可用示例，请将$APIZERO_API_KEY替换为你的真实密钥：
curl -sS \ -X POST \ -H "X-API-Key: $APIZERO_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "ua": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/125.0.0.0 Safari/537.36", "platform": "Win32", "language": "zh-CN", "timezone": "Asia/Shanghai", "timezoneOffset": -480, "screenWidth": 1920, "screenHeight": 1080, "colorDepth": 24, "pixelRatio": 1, "hardwareConcurrency": 8 }' \ "https://v1.apizero.cn/api/browser-fingerprint"说明：
- 如果只想要快速验证，可以只传
ua一个字段。 - 建议将敏感信息（如 API Key）从代码中剥离，使用环境变量或配置中心管理。
返回结果解读
成功响应（HTTP 200）示例：
{ "code": 0, "msg": "成功", "request_id": "abc123", "data": { "fingerprint_id": "a1b2c3d4...", "risk": 72, "risk_level": "high", "risk_label": "高风险", "timestamp": 1715097600, "factors": [ { "name": "webdriver", "desc": "WebDriver 标记为 true", "score": 30 }, { "name": "virtual_gpu", "desc": "WebGL 渲染器包含虚拟/软渲染特征: SwiftShader", "score": 15 } ], "anomalies": [ "UA 声称 Windows 但 platform 不匹配" ], "device_profile": { "browser": "Chrome 125", "os": "Windows", "device_type": "Desktop", "screen": "1920x1080", "cores": 8, "memory": "8GB", "gpu": "ANGLE (NVIDIA, GeForce RTX 3060)", "touch": false, "fonts_count": 42, "plugins_count": 3 } } }关键字段说明
fingerprint_id: 本次指纹的唯一标识，可用于关联上下文或去重。risk: 0-100的完整评分，数值越高风险越大。risk_level: 等级枚举：safe(0-20)、low(21-40)、medium(41-60)、high(61-80)、critical(81-100)。factors: 命中的具体风险因子列表，每个因子包含名称、描述和贡献的分数。anomalies: 检测到的异常项（如UA与平台不匹配）。device_profile: 识别出的设备特征概览，可用于人工核验。
错误处理与常见错误
1. 429 Too Many Requests (QPS超限)
当请求频率超过5 QPS时，API会返回HTTP 429或自定义的code: 429。此时客户端应：
- 等待至少200ms后重试（指数退避）。
- 对于非关键路径，可以暂时降级为默认放行或本地简单校验。
2. 400 Bad Request (参数错误)
常见原因：
ua缺失或为空字符串。- 请求体不是合法的JSON格式。
Content-Type不是application/json。
建议在发送请求前进行参数校验，避免无效请求浪费配额。
3. 401 Unauthorized (鉴权失败)
API Key 无效或未携带。请检查X-API-Key头的值是否正确。
4. 5xx 服务端错误
当服务器临时不可用时（极少发生），建议客户端实现重试策略：最多重试3次，间隔指数递增（1s、2s、4s），并在重试失败后记录日志并人工介入。
工程化注意事项
1. 并发控制与本地队列
由于QPS只有5，如果业务侧有多个入口（如登录、准备、下单同时调用），建议引入一个全局请求队列或令牌桶。例如：在入口层设置rate: 4/s，剩余1 QPS作为缓冲。
2. 缓存策略
对于短时间内相同指纹（如同一设备频繁触发检测），可以缓存fingerprint_id对应的风险评估结果，TTL建议设置为15-30秒。这样可大幅减少API调用次数，同时不影响实时性。
3. 降级与断路器
设计一个断路器：当连续5次请求返回429或5xx时，暂时熔断该API调用，改由本地规则（例如对可疑UA正则匹配）做初步判断，并异步记录失败次数。待API恢复后再切回。
4. 异步批处理
如果历史数据需要批量重分析（例如几十万条），建议将任务切分成多个小批次，每批次间隔0.2秒（即每秒5批次）。这样可以平摊请求，避免超出QPS。
5. 监控告警
建议对API调用设置以下指标：
- 请求耗时（P99 > 3s 告警）
- 请求失败率（>5% 告警）
- QPS接近限制（>4.5/s 告警）
参考文档
- 官方API文档：https://apizero.cn/aidocs/browser-fingerprint
- 原始文档（Markdown）：https://apizero.cn/aidocs/browser-fingerprint/raw.md
 锋哥原创出品，必属精品)
