接口参考
通用约定
所有 /api 接口共用以下约定: 统一响应结构、错误码、限速与缓存。接口无需鉴权, 支持 CORS 跨域, 可以在浏览器前端直接调用。
统一响应格式
JSON
{
"code": 200,
"data": {},
"msg": "success"
}| 字段 | 说明 |
|---|---|
code | 业务状态码, 200 为成功; 失败时等于对应的 HTTP 状态码 |
data | 业务数据, 结构见各接口文档; 失败时为 null |
msg | 成功为 success, 失败为中文错误说明, 仅供排查, 不要用来做分支判断 |
以
code判定成败, 不要只看 HTTP 状态码; 响应里的可选字段在无数据时省略, 按开放式对象解析, 缺字段不应报错。
错误码
| code | 含义 | 处理建议 |
|---|---|---|
400 | 参数错误: IP 格式无效、ASN 超出范围、代理检测缺少 enableProxyDetection | 修正请求, 不要重试 |
404 | 资源不存在 (如 ASN 在 RIPEstat 无记录) | 不要重试 |
408 | 上游查询超时 (BGP) | 稍后重试 |
429 | 超过限速 | 按 Retry-After 退避后重试 |
500 | 服务内部错误 | 指数退避重试, 持续出现请反馈 |
503 | 上游暂不可用 (BGP) | 稍后重试 |
限速
按客户端 IP 独立计数, 每个接口一分钟一个固定窗口:
| 接口 | 限额 |
|---|---|
/api/query | 600 次 / 分钟 |
/api/bgp/* | 60 次 / 分钟 |
/api/proxy-detection | 30 次 / 分钟 |
/ 及其他接口 | 300 次 / 分钟 |
每个响应都带限速头:
| 响应头 | 说明 |
|---|---|
X-RateLimit-Limit | 窗口内允许的总次数 |
X-RateLimit-Remaining | 本窗口剩余次数 |
X-RateLimit-Reset | 窗口重置时间, RFC 3339 格式 |
Retry-After | 仅超限时返回, 建议等待的秒数 |
超限时 HTTP 状态码为 429, 响应体多一个 retryAfter 字段 (秒):
JSON
{
"code": 429,
"data": null,
"msg": "请求过于频繁,请稍后重试",
"retryAfter": 46
}- 批量查询请在本地做缓存、去重和节流, 不要逐条裸打
- 命中
429按Retry-After等待后再试, 不要立即重发 - 可以读
X-RateLimit-Remaining实时掌握剩余次数, 接近 0 时主动放慢
缓存
接口响应带 Cache-Control, 调用方可以按它在本地缓存:
| 接口 | Cache-Control |
|---|---|
/api/query | public, max-age=300 |
/api/bgp/:asn | public, max-age=1800 |
/api/proxy-detection | public, max-age=60 |
/ (纯文本 IP) | no-store |
同一 IP 的归属信息短时间内基本不变, 批量场景建议按 IP 缓存至少 5 分钟。