域名验证API接口用于校验指定域名当前是否处于注册、解析或有效状态，支持批量与单次两种调用模式。

接口基础地址为 https://api.yourdomain.com/v1/domain/verify，采用 HTTPS 协议API域名验证接口，请求方式支持 GET 与 POST，鉴权方式为 Header 携带 Bearer Token。

接下来会详细地把参数怎么填写、调用的步骤是怎么走的、最后返回的结构长什么样, 还有遇到异常情况的时候该怎么处理这些东西, 全部都完整地给大家说明清楚。

请求参数说明

阜新市自然资源事务服务中心

参数名 类型 必填 说明
domain string 是 待验证的域名，不含协议前缀，如 example.com
check_type string 是 验证类型：registry（注册状态）、dns（解析状态）、full（完整校验）
ttl int 否 DNS 查询 TTL 上限（秒），默认 300
batch_list string[] 否 批量验证时传入，最多 50 个域名
callback_url string 否 异步回调地址API域名验证接口，仅批量异步模式使用

这是一个调用的演示案例, 采用的方法是POST。

POST /v1/domain/verify
Authorization: Bearer 
Content-Type: application/json
{
  "domain": "gname.xin",
  "check_type": "full"
}

调用流程

1. 你应该先申请到一个 API Key 这个东西, 然后你才能够在 Header 这里面去做这个鉴权的事情。

2. 构造请求体, 填写domain与check_type；批量场景使用batch_list。

3. 发送HTTPS请求的时候, 如果是在同步模式下, 会在3秒内返回结果。如果是批量的操作, 而且数量超过20条的话, 建议切换为异步模式, 并且要传入callback_url。

4. 你需要对接收到的JSON数据进行解析, 然后提取里面的status字段, 通过查看这个字段的值到底是什么, 来确认验证的步骤是已经成功通过了, 还是并没有通过。

返回结果

同步返回示例：

{
  "code": 0,
  "message": "success",
  "data": {
    "domain": "gname.xin",
    "registered": true,
    "dns_resolvable": true,
    "name_servers": ["ns1.dns.com", "ns2.dns.com"],
    "check_time": "2026-11-08T12:00:00Z"
  }
}

API域名验证接口怎么调？参数、流程与返回示例详解(图1)

code 的值是 0, 这表示请求已经成功；同时, 《data.registered》这个字段对应的是注册的状态信息, 而《data.dns_resolvable》这个字段对应的是 DNS 可解析性的状态。

常见错误码

code 含义 处理建议
1001 Token 无效或过期 重新获取鉴权凭证
1002 参数缺失或格式错误 检查 domain 是否含协议前缀
1003 批量数量超限 单次 batch_list 不超过 50
1004 服务限流（429） 按 Retry-After 头等待后重试
2001 域名不存在 确认拼写，或改用 check_type=registry 单独查询

使用注意事项

接口的每秒查询次数是被限制了。对于每一个特定的键值来说, 限制值是每一秒一百次的意思。如果遇到超量的状况, 就会发生错误代码为一千零四的限流机制。在真实生产的环境里面, 必须提前把请求队列安排妥当并且准备好后退躲避的方案。

当 check_type=full 被设定为全检模式的时候, 它会依次去串联调用注册局的查询和 DNS 的查询, 这样做会使得整体的耗费时间变长, 相比于单独只做 dns 查询的场景来说, 大概会增加 1–2 秒的时间, 所以在高并发的应用场景里面, 建议把这种调用方式拆分开来进行处理。

域名的参数必须是纯小写的形式, 并且不可以包含 http:// 或者 www. 这样的前缀, 如果出现这种情况的话, 系统将会返回 1002 这个错误代码。

回调地址必须是HTTPS协议, 只有当响应状态码是200的时候, 才能算作成功送达。如果没有得到响应的话, 系统就要在5分钟之内进行3次重试操作。