> For the complete documentation index see https://domscan.net/llms.txt. Markdown versions of every docs page are available by appending .md to the page URL.

Source: https://domscan.net/zh/docs/error-codes

# 错误代码

查看 错误代码 API 文档，了解请求参数、响应字段、代码示例以及 DomScan 集成的错误处理。

### 结构化错误

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

```json
{
  "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"
  }
}
```

### 错误字段

| 字段 | 说明 |
| --- | --- |
| `code` | 稳定、可供程序识别的错误码。错误码不会被重命名，因此可以放心用于条件分支。 |
| `message` | 便于阅读的错误说明。措辞可能会调整，请勿用程序解析。 |
| `type` | 错误的大致类别，例如 `validation_error`、`authentication_error` 或 `rate_limit_error`。 |
| `status` | HTTP 状态码，会在响应正文中重复出现，方便写入日志和队列。 |
| `retryable` | 稍后重试同一请求是否有可能成功。 |
| `request_id` | 唯一的请求标识符，与 `X-Request-Id` 响应头一致。 |
| `docs_url` | 指向解释该错误的文档章节的链接。 |
| `suggestion` | 可选的提示，说明如何修正请求。 |
| `details` | 可选的结构化上下文，例如允许的方法或无效的参数。 |
| `retry_after` | 可选，表示重试前需要等待的秒数，同时也会通过 `Retry-After` 响应头返回。 |

### 常见错误码

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

| 错误码 | HTTP 状态码 | 类型 | 是否可重试 | 说明 |
| --- | --- | --- | --- | --- |
| `BAD_REQUEST` | 400 | `validation_error` | 否 | 参数缺失或无效 |
| `MISSING_PARAMETER` | 400 | `validation_error` | 否 | 缺少必需的参数 |
| `INVALID_PARAMETER` | 400 | `validation_error` | 否 | 参数的值无效 |
| `INVALID_JSON` | 400 | `validation_error` | 否 | 请求正文不是有效的 JSON |
| `INVALID_DOMAIN` | 400 | `validation_error` | 否 | 域名格式无效 |
| `UNSUPPORTED_TLD` | 400 | `validation_error` | 否 | 不支持该 TLD |
| `SUBDOMAIN_NOT_SUPPORTED` | 400 | `validation_error` | 否 | 此端点只接受可注册的域名，不接受子域名 |
| `VALIDATION_ERROR` | 422 | `validation_error` | 否 | 请求格式正确，但无法处理 |
| `AUTH_REQUIRED` | 401 | `authentication_error` | 否 | 未提供 API 密钥或会话 |
| `INVALID_API_KEY` | 401 | `authentication_error` | 否 | API 密钥无效或已被撤销 |
| `INSUFFICIENT_CREDITS` | 402 | `credits_error` | 否 | 您的账户积分不足，无法完成此请求 |
| `FORBIDDEN` | 403 | `permission_error` | 否 | 您没有执行此操作的权限 |
| `NOT_FOUND` | 404 | `not_found_error` | 否 | 端点或资源不存在 |
| `METHOD_NOT_ALLOWED` | 405 | `request_error` | 否 | 该端点存在，但不接受此 HTTP 方法。`Allow` 响应头会列出支持的方法。 |
| `CONFLICT` | 409 | `conflict_error` | 否 | 请求与资源的当前状态冲突 |
| `IDEMPOTENCY_CONFLICT` | 409 | `conflict_error` | 否 | 该幂等键已被用于另一个不同的请求 |
| `IDEMPOTENCY_KEY_REUSED` | 422 | `validation_error` | 否 | 此 `Idempotency-Key` 在过去 24 小时内已用于另一个不同的请求。新请求请使用新的密钥。 |
| `IDEMPOTENCY_IN_PROGRESS` | 409 | `conflict_error` | 是 | 带有此 `Idempotency-Key` 的请求仍在运行。请稍后重试以获取其已存储的响应。 |
| `RATE_LIMITED` | 429 | `rate_limit_error` | 是 | 请求过多 |
| `INTERNAL` | 500 | `api_error` | 否 | 发生意外的服务器错误。如果问题持续出现，请附上请求 ID 联系支持团队。 |
| `UPSTREAM_ERROR` | 502 | `upstream_error` | 是 | 上游数据源返回了无法使用的响应 |
| `UPSTREAM_UNAVAILABLE` | 503 | `upstream_error` | 是 | 上游数据源暂时不可用 |
| `SERVICE_UNAVAILABLE` | 503 | `upstream_error` | 是 | 服务暂时不可用 |
| `TIMEOUT` | 504 | `timeout_error` | 是 | 上游数据源或注册机构未在规定时间内响应 |

### 重试指南

- 仅当 `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` 对象中读取错误详情。