Коды ошибок
Изучите документацию 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.