На этой странице

Ошибки

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исправьте запроснеобязательный

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

rate_limitedповтор поможетнеобязательный

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

service_unavailableповтор поможетнеобязательный

Сбой на нашей стороне: сервис не смог обработать запрос. Ваш запрос корректен, страница тут ни при чём. Повторите через 15 секунд - обычно хватает второй попытки. Сбой на нашей стороне, повторите позже.

bad_requestисправьте запроснеобязательный

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

method_not_allowedисправьте запроснеобязательный

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

ssrf_blockedисправьте запроснеобязательный

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

host_unresolvedисправьте запроснеобязательный

Домен не существует или не отвечает DNS. Это не запрет: проверьте адрес на опечатку. Домен не существует или не отвечает DNS - проверьте адрес на опечатку.

read_failedисправьте запроснеобязательный

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

source_refusedисправьте запроснеобязательный

Сайт не ответил нашему серверу: соединения не было, чтение упало с 5xx. Это не ошибка вашего запроса - ссылка корректна. Повторять эту же ссылку бессмысленно, если другие страницы того же сайта открываются: возьмите другой источник. Сайт не ответил нашему серверу: соединения не было, чтение упало с 5xx. Запрос корректен - это серверный сбой, а не ваша ошибка.

search_unavailableповтор поможетнеобязательный

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

upstream_timeoutповтор поможетнеобязательный

Источник не ответил за отведённое время. Это сторона сайта, а не ошибка вашего запроса: так ведут себя медленные сайты и сайты, блокирующие автоматическое чтение. Повторите через 60 секунд; если снова не выйдет - возьмите другой источник. Повторите или сузьте задачу.

schema_invalidисправьте запроснеобязательный

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

extract_failedповтор поможетнеобязательный

Страница прочитана, но разбор не удался: модель не вернула данные по схеме. Повторить имеет смысл - сузьте схему или попросите меньше полей. Страница прочитана, но разбор не удался.

empty_resultисправьте запроснеобязательный

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

insufficient_fundsисправьте запроснеобязательный

Недостаточно кредитов на балансе. Повтор не поможет: пополните баланс в личном кабинете. Если аккаунт новый и Telegram ещё не подтверждён - подтвердите его и подпишитесь на канал в разделе «Баланс», за это начислим 100 ₽. Текущий остаток - инструмент get_usage. Пополнить баланс и сменить тариф: https://srezai.ru/dashboard/billing. Вопросы и нештатные случаи: support@srezai.ru (Пн-Пт, 10:00-19:00 МСК, ответ в течение 1 рабочего дня).

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

400 Bad Requestошибка запросанеобязательный

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

401 Unauthorizedаутентификациянеобязательный

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

405 Method Not Allowedметоднеобязательный

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

429 Too Many Requestsлимитнеобязательный

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

502 Bad Gatewayапстримнеобязательный

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

503 Service Unavailableнедоступнонеобязательный

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

504 Gateway Timeoutтаймаутнеобязательный

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

Готовая обработка в SDK

Официальные клиенты для Python и JavaScript уже различают эти ошибки: на каждый код code заведён свой класс исключения, а повторы с задержкой сделаны только там, где они осмысленны. Разбирать code вручную не нужно:

python
from srezai import SrezAI, RateLimited, SsrfBlocked, Unauthorized

client = SrezAI()

try:
    page = client.read_url("https://example.com")
except Unauthorized:
    print("ключ не принят - проверьте SREZAI_API_KEY")
except SsrfBlocked:
    print("адрес во внутренней сети - читать нельзя")
except RateLimited as e:
    # Повторы уже сделаны внутри; сюда попадаем, когда они исчерпаны
    print("лимит, попробуйте через", e.retry_after, "с")