使用说明
通用约定

接口参考

通用约定

本页目录

所有 /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/query600 次 / 分钟
/api/bgp/*60 次 / 分钟
/api/proxy-detection30 次 / 分钟
/ 及其他接口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/querypublic, max-age=300
/api/bgp/:asnpublic, max-age=1800
/api/proxy-detectionpublic, max-age=60
/ (纯文本 IP)no-store

同一 IP 的归属信息短时间内基本不变, 批量场景建议按 IP 缓存至少 5 分钟。