接口概述

API域名的这个验证的接口, 是用来用编程的方式去检查特定的域名, 看看它是不是已经把归属权确认好了, 或者是DNS解析也做完了验证, 这个功能是适合用在SSL证书的签发上面, 还有邮箱域名的绑定上面, 又或者是Saas应用的域名关联上面这些场景里的, 开发者是完全不用亲自登上去控制台的, 只要能够通过调用一次, 或者批量地去调用一下, 就可以拿到对应的域名的那个验证状态的。

接口基本信息

项目 说明
请求地址 https://api.example.com/v1/domain/verify
请求方法 POST
认证方式 Bearer Token(Header携带)
Content-Type application/json
频率限制 100次/分钟/账户

请求参数

请求内容里面的格式是JSON类型的, 关于各个参数具体代表的意义情况, 说明如下所示:

参数名 类型 必填 说明
domain string 是 待验证域名,支持主域名或子域名
verify_type string 是 验证方式:dns、http、email
record_id string 否 DNS TXT记录标识,verify_type为dns时可选
timeout int 否 超时秒数,默认30API域名验证接口,上限120

请求示例:

{
  "domain": "www.example.com",
  "verify_type": "dns",
  "timeout": 60
}

返回结果

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

字段 类型 说明
code int 状态码,0为成功
message string 状态描述
verified boolean 是否验证通过
verify_time string 完成时间(ISO 8601)
failure_reason string 失败原因(仅失败时返回)

这是一个成功的例子。

{
  "code": 0,
  "message": "success",
  "verified": true,
  "verify_time": "2026-11-18T10:30:00Z"
}

调用流程

API域名验证接口调用全解:请求参数、返回格式与常见错误码(图1)

1. 使用账户密钥生成了Bearer Token, 并且借助这种方式完成了身份认证操作。

2. 要结合实际的业务需求来选择具体的验证方式, 可以选择dns / http / email这种类型的验证办法。

3. 我们来构造那个POST请求, 然后以JSON体的形式把参数提交上去。

4. 需要对返回来的 verified 这个字段进行解析;如果发现它的值是 false;那么就要去读取 failure_reason;目的是为了找准出现问题的具体地方。

API域名验证接口调用全解:请求参数、返回格式与常见错误码(图2)

5. 完成对应设置之后重新调用, 建议间隔大于等于六十秒。

常见错误码

code 含义 处理建议
1001 域名格式非法 检查空格、长度及字符合法性
1002 未找到对应记录 确认DNS TXT或HTTP文件已配置且生效
1003 验证超时 增大timeout或等待DNS传播完成
1005 任务已存在 同域名同类型验证仅允许一个进行中
401 认证失败 检查Token是否过期或Header格式错误
429 频率超限 加入指数退避重试API域名验证接口,间隔≥1秒

注意事项

API域名验证接口调用全解:请求参数、返回格式与常见错误码(图3)

因为DNS记录在网路上面会进行全球范围的传播, 所以新的配置情况通常需要等待5分钟之后, 一直到48个小时才能够真正完成生效, 于是我们在第一次执行调用动作之后的那个瞬间, 建议用户先去耐心等待2分钟的时间, 然后再去尝试执行一次重试操作。

这个接口, 它只是会返回一个验证的结果, 至于说域名注册这样的操作, 或者解析的变更操作, 该接口都不会去执行的。

我们建议在生产环境之中, 对那些 verified=false 的情况, 来设置为自动重试队列, 这样可以避免人工去一条一条地进行排查。