错误代码

错误代码

结构化错误

每个 API 错误都会返回相同的 JSON 结构：一个 error 对象，包含稳定的 code、便于阅读的 message、type 与 HTTP status、表示是否可重试的 retryable、request_id 以及 docs_url。request_id 始终与 X-Request-Id 响应头一致，联系支持团队时请一并提供。

{
  "error": {
    "code": "INVALID_DOMAIN",
    "message": "域名格式无效",
    "suggestion": "请使用可注册的域名，例如 example.com",
    "type": "validation_error",
    "status": 400,
    "retryable": false,
    "request_id": "m5x7k2p-a9f3",
    "docs_url": "https://domscan.net/docs/check-availability"
  }
}

错误字段

常见错误码

以下是大多数客户端需要处理的错误码。部分端点会返回遵循相同规则的更具体的错误码；包含状态码、类型和重试行为的完整列表见 OpenAPI 规范中的 x-domscan-error-codes。RATE_LIMIT_EXCEEDED 仍可作为 RATE_LIMITED 的别名使用。

重试指南

• 仅当 retryable 为 true 时才重试。对于验证、身份认证和权限类错误，请先修正请求。
• 如果响应中包含 retry_after 或 Retry-After 响应头，请至少等待相应的秒数后再进行下一次尝试。
• 否则请使用带随机抖动的指数退避，例如依次等待 1、2、4 和 8 秒，并在尝试几次后停止。
• 创建批量任务或作业时，请发送 Idempotency-Key 请求头，这样重试的请求就不会产生重复的作业。
• 对于其他会扣除积分的 POST 请求，添加 Idempotency-Key 请求头后，重试将返回已存储的响应，而不会再次扣费。

兼容性

自 2026 年 10 月 10 日起，所有端点均采用此格式。部分端点原本就会返回的字段，例如 credits_remaining、purchase_url、login_url、success 或 meta，会在兼容期内继续保留，现有集成无需改动即可正常运行。新代码请从 error 对象中读取错误详情。