这个API域名验证接口, 是在应用发布的时候, 或者在进行域名绑定的场景里面, 来实时地校验一下那个指定的域名到底是不是已经完成了ICP备案登记的操作, 同时也校验一下它的DNS解析配置是不是也已经做好了。

这个接口是以RESTful的格式对外去提供的, 它支持GET这种方式, 也支持POST这种方式进行调用, 它单次响应的时间通常是在200毫秒以内的, 它是可以直接嵌入到注册业务流程当中去的, 也是可以嵌入到 CDN接入业务流程中的, 同样也是可以直接嵌入到证书申请的业务流程里面的, 这些业务流程都是可以包含它的。

接口基本信息

接口地址：https://api.gname.xin/v1/domain/verify

请求的方法可以是GET, 也可以是POST。

认证方式是使用Bearer Token, 也就是在请求的Header里面携带Authorization字段, 这个字段的值是Bearer后面加上空格, 再跟上{token。

数据格式是, 请求体和响应体都是JSON。

频率限制：单Token 100次/分钟，超限返回429

请求参数

参数名 位置 类型 必填 说明
domain query / body string 是 待验证的完整域名大城群众说事，如 example.com
record_type query / body string 否 验证的DNS记录类型，默认 TXT，支持 A、CNAME
expect_value query / body string 否 期望解析到的目标值，缺省时仅验证域名是否存在
batch body array 否 批量验证，最多20个域名API域名验证接口，仅POST支持

返回结果

{
  "code": 0,
  "message": "success",
  "data": {
    "domain": "example.com",
    "verified": true,
    "dns_resolved": true,
    "icp_filed": true,
    "checked_at": "2026-10-22T10:00:00Z"
  }
}

代码 code 的值如果是 0, 那就意味着调用是成功的。域名验证是否通过要看字段 verified 的内容, 如果它是 true, 就表示验证通过了, 如果它是 false, 就说明没有通过, 关于具体的原因, 大家可以去查看字段 message。

调用流程

API域名验证接口接入指南：调用参数、流程与报错处理(图1)

1. 前往平台那边提交申请API Token的请求, 然后把那个专属于您的密钥给拿到手。

2. 把Token写到请求的Header里面去, 接着按照前面提到的那些要求, 把这些参数全部组合起来以完成请求组装的动作。

3. 向 api.gname.xin 这个地址去发起请求, 这个请求的方法可以是 GET , 也可以是 POST , 要发往那个对应的接口端点。

4. 需要先去解析那个返回的格式为JSON的数据。然后在得到数据之后, 我们要去看一看里面的verified这个字段。通过观察这个字段的值, 就可以知道验证操作最终是什么样的结果了。

5. 假如是批量处理的情形, 就把 batch 数组里面的每一个结果单独拿出来, 一条接一条地进行处理。

常见错误码

code 含义 处理建议
40001 参数缺失或格式错误 检查 domain 是否为合法域名
40003 Token无效或过期 重新申请或刷新Token
40004 域名未备案 提示用户先完成ICP备案
42901 触发频率限制 使用指数退避重试API域名验证接口，间隔≥2s
50000 服务内部异常 稍后重试，持续出现请联系技术支撑

注意事项

单次批量验证的上限是20个域名, 你要是超过了这个数量, 系统会直接返回40001错误。

接口所返回的那个被html标签标注为 icp_filed 的字段, 它是直接依赖于对备案数据库进行的同步操作的, 所以存在最多能够达到24个小时之久的时间延迟问题, 因此对于新近进行备案的域名来说, 建议大家都应该先等待满24小时的时间周期以后, 再来做出那些具有权威性质的判断行为。

在生产环境里面的时候, 必须要要在代码当中去处理那个因为网络超时产生的问题, 这里建议把它设置成5秒钟的时间, 同时呢, 还要把针对429那个状态码的重试逻辑给加上, 这样做就是为了避免它把主流程当中的业务给阻塞掉。