> 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/ru/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` | Нет | Непредвиденная ошибка сервера. Если она повторяется, обратитесь в поддержку и укажите идентификатор запроса. |
| `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` позволяет получить при повторе сохраненный ответ вместо повторного списания.

### Совместимость

С 10 октября 2026 года этот формат используют все конечные точки. Поля, которые некоторые конечные точки возвращали и раньше, например `credits_remaining`, `purchase_url`, `login_url`, `success` или `meta`, сохраняются на переходный период, поэтому существующие интеграции продолжают работать. В новом коде читайте сведения об ошибке из объекта `error`.
