> 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/ja/docs/error-codes

# エラーコード

エラーコード APIのドキュメントで、リクエストパラメーター、レスポンスフィールド、コード例、DomScan連携のエラー処理を確認できます。

### 構造化されたエラー

すべての API エラーは同じ JSON 構造で返されます。安定した `code`、読みやすい `message`、`type` と HTTP `status`、再試行の可否を示す `retryable`、`request_id`、`docs_url` を持つ `error` オブジェクトです。`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` オブジェクトから読み取ってください。