Справочник

Ошибки

API возвращает стандартные HTTP-коды. При ошибке тело ответа содержит машинный код в поле code и человекочитаемое сообщение в error — на русском и английском. Ветвитесь по code: текст может уточняться, код — нет.

Формат ошибки#

json

{
  "error": "Некорректный запрос. Поле query обязательно (до 300 символов). / Malformed request. The query field is required (up to 300 characters).",
  "code": "bad_request"
}

Проверяйте HTTP-код ответа, а не только тело. Успешный ответ — код 200. Поле code — из закрытого списка ниже, поэтому по нему можно ветвиться в коде. Текст в error — для человека и для модели: сначала по-русски, затем через / по-английски.

MCP-инструменты отдают ту же ошибку текстом, с кодом в квадратных скобках в начале первой строки:

text

[bad_request] Некорректный запрос. Поле query обязательно (до 300 символов). / Malformed request. The query field is required (up to 300 characters).

Коды ошибок#

unauthorizedисправьте запросoptional

Требуется API-ключ: заголовок Authorization: Bearer srz_live_… Проверьте ключ в заголовке Authorization.

rate_limitedповтор поможетoptional

Лимит запросов исчерпан. Подождите Retry-After секунд. Отказ по burst суточную квоту не расходует.

service_unavailableповтор поможетoptional

Сервис временно недоступен. Это сбой на нашей стороне, а не ошибка запроса. Сбой на нашей стороне, повторите позже.

bad_requestисправьте запросoptional

Некорректный запрос. Исправьте параметры запроса.

method_not_allowedисправьте запросoptional

Метод не поддерживается. Используйте POST. Используйте POST.

ssrf_blockedисправьте запросoptional

Адрес запрещён: разрешены только публичные http/https-ссылки. Дайте публичный http/https-адрес.

read_failedповтор поможетoptional

Не удалось прочитать страницу. Страница не отдала текст. Иногда помогает повтор с engine: "stealth".

search_unavailableповтор поможетoptional

Поисковые движки не ответили. Это временный сбой, а не отсутствие информации: повторите запрос через несколько секунд. Движки не ответили — это не отсутствие информации. Повторите через несколько секунд.

upstream_timeoutповтор поможетoptional

Запрос занял слишком долго. Повторите или сузьте задачу. Повторите или сузьте задачу.

schema_invalidисправьте запросoptional

Схема некорректна. Исправьте схему по указанному в тексте пути.

extract_failedповтор поможетoptional

Не удалось извлечь данные. Страница прочитана, но разбор не удался.

empty_resultисправьте запросoptional

Ничего не найдено. Запрос выполнен, результатов нет. Измените запрос.

Коды состояния#

400 Bad Requestошибка запросаoptional

Некорректное тело (не JSON) или пустой query. Лимит длины зависит от эндпоинта: 300 символов для поиска и изображений, 2000 для DeepResearch. Для скриншота страницы сюда же попадает недопустимый или внутренний адрес — с полем code: "ssrf_blocked" (приватные IP, нестандартные порты, локальные имена).

401 Unauthorizedаутентификацияoptional

Ключ отсутствует, недействителен или отозван. Тело — { error, code: "unauthorized" }, заголовок WWW-Authenticate: Bearer. См. Аутентификация.

405 Method Not Allowedметодoptional

Неверный HTTP-метод. Все эндпоинты /api/v1/* (поиск, изображения, скриншот, исследования) принимают только POST.

429 Too Many Requestsлимитoptional

Превышен burst-лимит или суточная квота. Поля reason и retryAfterSec, заголовок Retry-After. См. Лимиты.

502 Bad Gatewayапстримoptional

Поисковый движок или краулер недоступен, либо вернул некорректный ответ.

503 Service Unavailableнедоступноoptional

Сервис временно не настроен или на обслуживании. Сюда же попадает случай, когда ни один поисковый движок не ответил: код "search_unavailable". Это авария апстрима, а не отсутствие информации — пустой список результатов с кодом 200 в такой ситуации мы не отдаём.

504 Gateway Timeoutтаймаутoptional

Запрос к поисковому движку занял слишком долго (лимит 12 секунд). Повторите запрос.

Повторные попытки

На коды 429, 502 и 504 стоит повторять запрос с экспоненциальной задержкой. Для 429 используйте значение Retry-After.

4xx повторять бессмысленно

Коды 400 и 401 означают проблему в самом запросе — повтор без изменений даст ту же ошибку. Исправьте параметры или ключ. В терминах code это bad_request, schema_invalid, ssrf_blocked и unauthorized.