这个API域名验证接口, 它是用来通过程序化的那种方式, 去确认一下指定域名的归属情况, 还有解析状态到底怎么样, 大家得知道这一点。

核心的逻辑是这样的, 你要向这个接口提交一个域名, 然后接口就会给你返回该域名的验证状态, 这个状态具体包括几种情况, 比如已验证、未验证、解析异常或者解析中, 这些都是可能出现的。这种服务适用于那些对域名进行自动化管理的场景, 同时也适用于批量资产巡检这样的场景哦。

接口地址与请求方式

接口地址：/v1/domain/verify

请求方式：POST

所谓的认证的方式, 是通过一种叫做 Bearer Token 的玩意儿来实现的, 这种事儿一般是在 Header 这个字段里面, 去附带一个 Authorization 这个字段来完成的。

Content-Type：application/json

请求参数

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

参数名 类型 必填 说明
domain string 是 待验证域名API域名验证接口API域名验证接口，如 gname.xin
verify_type string 否 验证类型：dns / whois / ssl，默认 dns
lang string 否 返回语言，默认 zh-CN

调用示例

{
  "domain": "gname.xin",
  "verify_type": "dns",
  "lang": "zh-CN"
}

返回结果

{
  "code": 200,
  "domain": "gname.xin",
  "status": "verified",
  "message": "域名DNS解析验证通过",
  "details": {
    "ns": ["ns1.gname.xin", "ns2.gname.xin"],
    "verify_time": "2026-11-13T09:00:00Z"
  }
}

API域名验证接口怎么调用？参数、返回码与常见报错(图1)

status字段的数值可以是verified, 意思也就是已验证的状态, 也可以是unverified, 代表未验证, 或者是error, 说明解析出现了异常, 还有可能是pending, 表示正在解析的过程当中, 如果code值不是200的时候, 那么message这个字段就会负责描述具体是什么原因导致的错误。

常见报错与处理

出现了401, 这个情况是Token已经过期了或者没有提供, 所以需要去重新获取一下认证凭证, 拿到了之后再来 retry。

出现了404错误, 这是因为域名不存在, 或者该域名还没有被纳入到验证体系中, 所以请您确认一下域名的拼写是否正确以及它的注册状态。

返回结果是 429 , 意思是请求的频率太高等限流了, 系统的默认阈值是每分钟 100 次, 你现在需要做的就是去降低调用的频率, 或者是去申请把配额提升上去。

如果出现了状态码为 500 的情况, 这代表服务端遇到了临时性的错误。建议大家使用指数退避的方法来尝试重新进行请求操作, 而且最多只能重试 3 次, 超过这个次数就不再继续重试了。

注意事项

1. 域名的格式必须是完整的, 这里说完整啊, 就包括了你得带上那个顶级域名这部分内容, 绝对不行用那种通配符, 更不许填一个 IP 地址进来。

2. DNS 验证这事儿, 是依赖于 TTL 这个机制的, 所以新修改的解析记录, 最多需要等待30分钟这样才能够生效。

3. 在生产环境里需要去使用 HTTPS 来进行调用, 这样做是为了防止请求在传输这个过程当中被篡改。

4. 建议在批量验证的场景里, 配合上使用限流这个逻辑, 以此来避免去触发那个代码为 429 的限频错误, 这种情况是经常会被发现的。