> 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/ko/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` 객체에서 오류 세부 정보를 읽으세요.