Коды статусов · Документация Crawlbase

Два статуса, два вопроса

Большинство HTTP API возвращают один код статуса. Crawlbase возвращает два, потому что краулинг включает два уровня - инфраструктуру Crawlbase и целевой сайт за ней.

HTTP-статус

int

Статус вашего запроса к Crawlbase. 200 означает, что краулинг прошёл успешно; 520 означает, что он не удался, а cb_status объясняет причину; другие коды 4xx/5xx означают, что запрос был отклонён ещё до краулинга.

cb_status

intheader

Вердикт Crawlbase по краулингу после собственных проверок на блокировки, редиректы и содержимое. 200 означает пригодную страницу; другие коды описывают, что пошло не так.

original_status

intheader

Исходный HTTP-статус, который вернул целевой сайт. Полезно, когда сам сайт возвращает не-200 ответ, который нужно обработать (404, 403 и т. д.).

Ментальная модель

Всегда сначала проверяйте HTTP-статус. Если он 200, проверьте cb_status. Если и он 200, тогда проверьте original_status на наличие ошибок на стороне сайта.

Коды HTTP-статусов

Что вернул сам Crawlbase вашему клиенту.

Код	Значение	Действие
`200`	Запрос обработан. Проверьте `cb_status` для получения результата.	Перейдите к `cb_status`
`400`	Некорректный запрос: `url` отсутствует, не URL-кодирован или слишком длинный, либо у параметра недопустимое значение.	Исправьте запрос; повтор без изменений не поможет
`401`	Token отсутствует или недействителен.	Проверьте token; убедитесь, что он не был сброшен
`402`	Это рабочее пространство достигло месячного лимита расходов.	Повысьте лимит в консоли или дождитесь следующего периода
`403`	Аккаунт заблокирован (например, бесплатные кредиты израсходованы, а оплата не настроена) или достиг лимита расходов аккаунта.	Проверьте страницу «Оплата» в консоли
`429`	Достигнут лимит запросов для этого токена и целевого домена.	Сделайте паузу и повторите; см. Rate Limits
`500`	Внутренняя ошибка Crawlbase. Редкая и временная.	Повторите с задержкой; проверьте страницу статуса
`503`	Сервис временно недоступен.	Повторите с задержкой
`504`	Время ожидания запроса истекло до завершения краулинга (`cb_status` тоже `504`). Не тарифицируется.	Повторите с задержкой
`520`	Краулинг не удался. `cb_status` объясняет причину. Не тарифицируется.	Прочитайте `cb_status` и следуйте таблицам ниже

Коды cb_status

Что произошло во время краулинга. Возвращается в заголовке ответа cb_status (и в теле ответа при format=json) в каждом ответе на краулинг, успешном или нет. Ранее назывался pc_status; это имя по-прежнему отправляется как псевдоним.

Успех

Код	Значение
`200`	Страница успешно прокраулена. Тело ответа содержит HTML или JSON целевой страницы. `original_status` также может быть `404`, `410` или редиректом: это корректные ответы, они считаются успешными краулингами и тарифицируются.
`207`	Сайт ответил `200` с пустым телом. Считается успехом и тарифицируется; если вы ожидали контент, повторите запрос с JavaScript-токеном.

Целевой сайт ответил с ошибкой

Crawlbase достиг сайта, но сайт отклонил запрос. original_status содержит собственный статус сайта, и ни один из этих случаев не тарифицируется. 404 или 410 здесь не ошибка: такой ответ возвращается с cb_status 200.

Код	Значение
`704`	Сайт ответил другим неуспешным статусом. Прочитайте `original_status` и обработайте его как ответ сайта или укажите его в `custom_success_codes`, чтобы всё равно получить тело ответа.
`705`	Сайт ответил `403`, обычно это блокировка. Снизьте частоту запросов и разберитесь в причине, прежде чем повторять.
`706`	Сайт ответил `429` и ограничивает частоту ваших запросов. Сделайте паузу и снизьте частоту запросов.

Блокировка или сбой

Код	Значение	Что попробовать
`503`	Crawlbase распознал страницу блокировки или CAPTCHA.	Переключитесь с Normal-токена на JavaScript-токен; если уже используете JavaScript, сделайте паузу и повторите
`595`	Элемент `css_click_selector` не найден на странице.	Исправьте селектор или добавьте запасной вариант, например `#start-button,body`
`599`	Внутренняя ошибка Crawlbase.	Повторите с задержкой; если ошибка сохраняется, отправьте `rid` в поддержку
`5xx-7xx`	Любой другой код `5xx`, `6xx` или `7xx` означает внутренний сбой или сбой, специфичный для сайта. Ни один из них не тарифицируется.	Повторите с ограничением числа попыток; если ошибка сохраняется, отправьте `rid` в поддержку

Чтение ответа

curl -i 'https://api.crawlbase.com/?token=YOUR_TOKEN&url=https%3A%2F%2Fexample.com'


# HTTP/1.1 200 OK
# cb_status: 200
# original_status: 200
# url: https://example.com/
# content-type: text/html
from crawlbase import CrawlingAPI


api = CrawlingAPI({'token': 'YOUR_TOKEN'})
res = api.get('https://example.com')


# Layer 1: did the crawl succeed? 520 means it failed.
if res['status_code'] != 200:
    raise RuntimeError(f"Crawl failed: {res['status_code']}, cb_status {res['cb_status']}")


# Layer 2: did Crawlbase get content? 207 means an empty page.
if res['cb_status'] == 207:
    raise RuntimeError("Empty page; retry with the JavaScript token")


# Layer 3: did the target site return content?
if res['original_status'] != 200:
    print(f"Site returned {res['original_status']}")


print(res['body'])

Дальнейшие шаги

Обработка ошибок

Паттерны для повторных попыток, очередей недоставленных сообщений и наблюдаемости.

Лимиты запросов

Конкретные рекомендации по ошибкам 429 и параллелизму.