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

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

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

HTTP-статус

int

Статус вашего запроса к Crawlbase. 200 означает, что мы его обработали; 4xx/5xx означает, что не смогли.

pc_status

intheader

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

original_status

intheader

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

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

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

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

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

Код	Значение	Действие
`200`	Запрос обработан. Проверьте `pc_status` для получения результата.	Перейдите к `pc_status`
`401`	Token отсутствует или недействителен.	Проверьте token; убедитесь, что он не был сброшен
`402`	Закончились кредиты или истёк пробный период.	Пополните аккаунт
`403`	У токена нет доступа к этому продукту.	Используйте подходящий тип токена (Normal или JS)
`422`	Некорректный запрос - обычно отсутствующий или незакодированный URL.	Выполните URL-кодирование параметра `url`
`429`	Достигнут лимит параллельных запросов.	Сделайте паузу и повторите; см. Rate Limits
`500`	Внутренняя ошибка Crawlbase. Редкая и временная.	Повторите с задержкой; проверьте страницу статуса
`503`	Сервис временно недоступен.	Повторите с задержкой

Коды pc_status

Что произошло во время самого краулинга. Возвращается в виде заголовка ответа pc_status в каждом запросе с 200-OK.

Успех

Код	Значение
`200`	Страница успешно прокраулена. Тело ответа — это HTML или JSON целевой страницы.
`201`	Async-запрос принят. Результат будет доставлен на ваш webhook или сохранён под `rid`.

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

Crawlbase достиг сайта, но сам сайт вернул не-2xx ответ. Тело содержит то, что прислал сайт.

Код	Значение
`404`	Целевая страница не существует.
`410`	Целевая страница была окончательно удалена.
`451`	Страница заблокирована по юридическим причинам в целевой стране.

Заблокировано или отфильтровано

Код	Значение	Что попробовать
`520`	Целевой сайт вернул пустой или недействительный ответ.	Повторите запрос; переключитесь на JS-токен, если ещё не используете
`521`	Целевой сайт отклонил соединение.	Проверьте корректность URL; сайт может быть недоступен
`522`	Crawlbase не удалось связаться с целевым сайтом (тайм-аут).	Повторите запрос; рассмотрите настройку `page_wait`
`523`	Целевой сайт вернул ошибку TLS-рукопожатия.	Возможны проблемы с сертификатом сайта; сообщите в поддержку
`525`	Бот-проверку не удалось решить автоматически.	Переключитесь на JS-токен; некоторые сайты могут потребовать индивидуальной обработки
`599`	Общий сбой на стороне источника.	Повторите запрос с задержкой

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

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

# HTTP/1.1 200 OK
# pc_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 Crawlbase accept the request?
if res['status_code'] != 200:
    raise RuntimeError(f"Crawlbase: {res['status_code']}")

# Layer 2: did Crawlbase succeed in fetching the page?
if res['pc_status'] != 200:
    raise RuntimeError(f"Crawl failed: {res['pc_status']}")

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

print(res['body'])

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

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

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

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

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