登录

状态码

Crawlbase 在每个响应中返回两个状态信号：标准的 HTTP 状态，以及描述 Crawlbase 所做操作的 pc_status 头。下面是每种组合的含义。

两种状态，两个问题

大多数 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
401token 缺失或无效。验证 token；检查是否已被重置
402额度用尽或试用已过期。为账户充值
403token 无权访问此产品。使用正确的 token 类型（Normal 或 JS）
422请求格式错误，通常是缺失 URL 或 URL 未编码。对 url 参数进行 URL 编码
429已达到并发限制。退避后重试；参见 Rate Limits
500Crawlbase 内部错误。罕见且为暂时性。退避后重试；查看状态页面
503服务暂时不可用。退避后重试

pc_status 状态码

实际爬取过程中发生了什么。在每个 200-OK 请求上以 pc_status 响应头返回。

成功

状态码含义
200页面爬取成功。响应体为目标页面的 HTML 或 JSON。
201已接受 async 请求。结果将通过您的 webhook 推送或存储于对应的 rid 下。

目标站点返回错误

Crawlbase 已抵达站点，但站点本身返回了非 2xx 状态。响应体包含站点返回的内容。

状态码含义
404目标页面不存在。
410目标页面已被永久移除。
451页面在目标地区因法律原因被屏蔽。

被屏蔽或被过滤

状态码含义尝试方法
520目标站点返回了空响应或无效响应。重试；如尚未使用 JS token，可切换到 JS token
521目标站点拒绝了连接。检查 URL 是否正确；站点可能已宕机
522Crawlbase 无法访问目标站点（超时）。重试；考虑调整 page_wait
523目标站点返回了 TLS 握手错误。站点可能存在证书问题；请联系支持团队反馈
525无法自动解决机器人验证挑战。切换到 JS token；部分站点可能需要自定义处理
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 状态码和并发的具体指南。