Справочник разработчика

Коды ошибок

Изучите документацию API Коды ошибок, параметры запросов, поля ответов, примеры кода и обработку ошибок для интеграций DomScan.

Коды ошибок

Структурированные ошибки

Каждая ошибка 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"
  }
}

Поля ошибки

ПолеОписание
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.