PULL WHOIS · API REFERENCE
域名查询 API
一个接口拿到结构化的域名注册信息。服务端优先请求注册局 RDAP,未覆盖或失败时自动回退到 WHOIS 43 端口,并统一字段、日期、状态码与命名服务器格式。
认证:是否需要 API Key 由管理后台的「访问策略」决定。开启后请在请求头携带
限流:默认每 IP 每分钟 120 次,携带有效 API Key 每分钟 600 次。响应头包含
x-api-key 或 Authorization: Bearer <key>,密钥可在
管理后台 创建与停用;服务启动时的 API_KEYS 环境变量同样有效。
限流:默认每 IP 每分钟 120 次,携带有效 API Key 每分钟 600 次。响应头包含
ratelimit-limit、ratelimit-remaining、ratelimit-reset。
错误处理
所有失败响应都使用统一结构,HTTP 状态码与 error.code 同时表达语义。批量接口中单个域名失败不会影响其他结果。
| 状态码 | error.code | 说明 |
|---|---|---|
| 400 | INVALID_DOMAIN | 域名格式不合法,例如缺少后缀、包含非法字符或为 IP 地址。 |
| 400 | BAD_REQUEST | 查询参数或请求体不合法。 |
| 401 | UNAUTHORIZED | 服务开启 API Key 校验但未提供有效 Key。 |
| 404 | NOT_FOUND | 接口路径不存在。 |
| 429 | RATE_LIMITED | 触发限流,参考 Retry-After 响应头。 |
| 502 | UPSTREAM_UNAVAILABLE | RDAP 与 WHOIS 均无法返回结果,details.attempts 包含每次尝试。 |
| 504 | UPSTREAM_TIMEOUT | 注册局接口超时。 |
| 500 | INTERNAL | 未预期的服务端错误。 |
{
"success": false,
"error": {
"code": "INVALID_DOMAIN",
"message": "请输入完整域名(包含后缀),例如 example.com"
},
"meta": { "requestId": "req-4" }
}