域名交易市场 API 常见错误与排错指南：参数、鉴权与响应解读

适用场景

域名交易市场 API 适用于需要实时获取 EDNS 平台上公开挂牌域名信息的场景，例如：

• 站长扫货短米：通过用量说明、长度、后缀组合筛选，批量抓取优质未准备（或到期删除）域名。
• 行业趋势分析：定期拉取交易列表，统计热门后缀、平均成交价、交易类型分布。
• 域名估值辅助：将接口返回的挂牌用量说明作为参考维度之一，结合其他数据源做用量说明模型。

该 API 返回的是当前公开挂牌数据，不代表最终成交价，也不保证域名可用性，开发者应结合 WHOIS 等渠道二次验证。

接口能力边界

• 请求方式：GET
• 基础地址：https://v1.apizero.cn/api/domain-trade
• QPS 限制：5 请求/秒（超过会返回 429）
• 分页限制：pagesize最大 100，页码无硬上限但超过总页数会返回空列表
• 返回格式：JSON，统一包裹在{ "code": 0, "data": {...}, "msg": "成功" }结构中

注意：接口不承诺实时性，数据存在一定延迟（通常分钟级），不适合对秒级一致性有要求的场景。

参数与鉴权

鉴权方式

请求头中必须携带X-API-Key，值为你在平台申请的 API Key。没有 Key 的请求会得到 401 响应。

-H "X-API-Key: YOUR_API_KEY"

Query 参数一览

常见陷阱：

• max_price和max_length超过合理范围（如负数）会被忽略或返回空结果。
• suffix必须带点号（如.com），不带点会被视为非法参数，服务器返回 400。
• sale_type取值需与平台预设类型一致，大小写敏感；传入"一口价"有效，传入"yikoujia"无效。

curl 调试模板

以下 curl 命令演示如何携带鉴权头并传递筛选参数：

# 基础请求（第1页，每页50条） curl -sS -X GET \ -H "X-API-Key: $APIZERO_API_KEY" \ "https://v1.apizero.cn/api/domain-trade" # 带筛选：.com 后缀、价格≤1000元、长度≤6字符 curl -sS -X GET \ -H "X-API-Key: $APIZERO_API_KEY" \ "https://v1.apizero.cn/api/domain-trade?page=1&pagesize=100&suffix=.com&max_price=1000&max_length=6" # 仅获取一口价交易 curl -sS -X GET \ -H "X-API-Key: $APIZERO_API_KEY" \ "https://v1.apizero.cn/api/domain-trade?sale_type=%E4%B8%80%E5%8F%A3%E4%BB%B7"

请将$APIZERO_API_KEY替换为你的真实 Key。若使用 Windows cmd，需将单引号改为双引号。

返回值解读

成功响应示例（HTTP 200）：

{ "code": 0, "msg": "成功", "data": { "count": 50, "current_page": 1, "total_pages": 1234, "list": [ { "name": "abc.com", "price": "5000", "sale_type": "一口价" } ] } }

字段说明

注意：

• price是字符串，可能有"面议"等非数字值，解析时建议先转换或做类型判断。
• sale_type可能为空字符串（表示未分类），不能假定必有值。
• 分页时count可能小于pagesize（最后一页），但总页数已由total_pages给出。

常见错误与排错

1. 401 Unauthorized

现象：HTTP 状态码 401，响应 JSON 包含"code": 401。

原因分析：

• 请求头未携带X-API-Key。
• API Key 无效或已过期。
• Key 拼写错误（注意大小写和连字符）。

排错步骤：

1. 检查是否在 curl 中添加了-H "X-API-Key: ..."。
2. 确认 Key 未被空格包围（如-H "X-API-Key: key123 "末尾空格会导致失败）。
3. 在平台控制台重新生成 Key 后重试。

2. 400 Bad Request

现象：HTTP 400，msg字段通常描述具体错误。

常见触发原因：

• pagesize大于 100。
• page小于 1。
• max_price或max_length传入非数字（如字符串abc）。
• suffix不含点号（如传com而非.com）。
• sale_type包含不可见字符或编码异常。

排错方法：

• 先去掉所有可选参数，只保留最基本的page=1&pagesize=10确认接口可通。
• 逐步添加参数，每次检查响应是否变为 400。
• 对 URL 进行 encode（中文参数如一口价需 URL 编码，curl 会自动处理，但手动拼 URL 时容易出错）。

3. 429 Too Many Requests

现象：HTTP 429，响应可能包含Retry-After头部。

原因：超过 QPS 5。

处理方案：

• 串行请求之间至少间隔 200ms（1000ms/5=200ms）。
• 使用指数退避重试，首次重试等待 1s，后续加倍。
• 避免密集循环分页，建议使用异步批量但控制并发数 ≤5。

4. 空结果或不符合预期的数据

现象：data.list为空数组（[]），但code=0。

原因：

• 筛选条件过于严格，如max_price=100&max_length=3&suffix=.xyz可能没有匹配项。
• 当前页数大于total_pages（此时data.list也会为空）。
• 平台暂无该条件的数据。

排错：

• 调大max_price或max_length观察是否有数据。
• 先不加过滤条件请求第 1 页，确认整体有数据后逐渐收紧条件。
• 检查total_pages是否为零，若为零说明该数据集无任何记录。

5. 字段类型与格式陷阱

• price为字符串，曾遇到"5000""面议"，使用parseInt前需判断。
• sale_type可能是null或空字符串，代码中应做容错。
• 某些域名的name包含 IDN（国际化域名），返回的是 Punycode（如xn--p1ai.com），直接使用即可。

6. 分页循环失控

场景：想拉取全部数据，但因current_page一直不变或total_pages重新计算导致死循环。

安全做法：

page = 1 while True: resp = call_api(page=page, pagesize=100) data = resp["data"] if not data["list"]: break # 空列表则退出 process(data["list"]) if page >= data["total_pages"]: break page += 1

注意：不能在循环内修改pagesize，否则total_pages会变，导致边界判断出错。

工程化注意事项

1. 重试与退避：对 429、500、502 等可重试状态码，建议实现指数退避（初始 1s，最多重试 3 次）。
2. 日志记录：记录每次请求的 URL（隐藏 Key）、响应码、耗时、返回条数，便于后期排查。
3. 参数校验：发送前在客户端校验pagesize≤100、page≥1、max_price为数字，避免无效请求浪费配额。
4. 超时设置：建议设置连接超时 5s、读取超时 10s，防止因网络抖动导致线程阻塞。
5. 缓存策略：由于数据变化不频繁，可以缓存同一条件的结果 5~10 分钟，减少调用次数。

参考文档

• 域名交易市场 API 文档页
• 原始文档 Markdown