Codes de statut · Documentation Crawlbase

Deux statuts, deux questions

La plupart des API HTTP renvoient un seul code de statut. Crawlbase en renvoie deux, car le crawling implique deux couches : l'infrastructure de Crawlbase et le site cible derrière celle-ci.

Statut HTTP

int

Le statut de votre requête vers Crawlbase. 200 signifie que le crawl a réussi ; 520 signifie qu'il a échoué et cb_status indique pourquoi ; les autres codes 4xx/5xx signifient que la requête a été refusée avant tout crawl.

cb_status

intheader

Le verdict de Crawlbase sur le crawl, après ses propres vérifications de blocage, de redirection et de contenu. 200 signifie une page exploitable ; les autres codes décrivent ce qui a échoué.

original_status

intheader

Le statut HTTP brut renvoyé par le site cible. Utile lorsque le site lui-même renvoie un code non-200 que vous devez gérer (404, 403, etc.).

Le modèle mental

Vérifiez toujours d'abord le statut HTTP. S'il est à 200, vérifiez ensuite cb_status. Si celui-ci est à 200, vérifiez alors original_status pour les erreurs côté site.

Codes de statut HTTP

Ce que Crawlbase lui-même a renvoyé à votre client.

Code	Signification	Action
`200`	Requête traitée. Vérifiez `cb_status` pour le résultat.	Passez à `cb_status`
`400`	Requête invalide : `url` manquant, non encodé en URL ou trop long, ou un paramètre avec une valeur invalide.	Corrigez la requête ; la renvoyer telle quelle ne servira à rien
`401`	Token manquant ou invalide.	Vérifiez le token ; assurez-vous qu'il n'a pas été réinitialisé
`402`	Ce workspace a atteint son plafond de dépenses mensuel.	Relevez le plafond dans la console, ou attendez la période suivante
`403`	Le compte est bloqué (par exemple, les crédits gratuits sont épuisés et aucune facturation n'est configurée) ou a atteint sa limite de dépenses au niveau du compte.	Consultez la page Facturation dans la console
`429`	Limite de débit atteinte pour ce token et ce domaine cible.	Patientez puis réessayez ; voir Rate Limits
`500`	Erreur interne Crawlbase. Rare et passagère.	Réessayez avec un backoff ; consultez la page de statut
`503`	Service temporairement indisponible.	Réessayez avec un backoff
`504`	La requête a expiré avant la fin du crawl (`cb_status` vaut aussi `504`). Non facturé.	Réessayez avec un backoff
`520`	Le crawl a échoué. `cb_status` indique pourquoi. Non facturé.	Lisez `cb_status` et suivez les tableaux ci-dessous

Codes cb_status

Ce qui s'est passé pendant le crawl. Renvoyé sous forme d'en-tête de réponse cb_status (et dans le body avec format=json) sur chaque réponse de crawl, réussie ou non. Anciennement nommé pc_status, toujours envoyé comme alias.

Succès

Code	Signification
`200`	Page crawlée avec succès. Le body contient le HTML ou le JSON de la page cible. `original_status` peut aussi valoir `404`, `410` ou une redirection : ce sont des réponses valides, qui comptent comme des crawls réussis et sont facturées.
`207`	Le site a répondu `200` avec un body vide. Compte comme un succès et est facturé ; si vous attendiez du contenu, réessayez avec le JavaScript token.

Le site cible a renvoyé une erreur

Crawlbase a atteint le site, mais le site a refusé la requête. original_status contient le statut propre du site, et aucun de ces cas n'est facturé. Un 404 ou un 410 n'est pas une erreur ici : il revient avec cb_status 200.

Code	Signification
`704`	Le site a répondu avec un autre statut d'échec. Lisez `original_status` et traitez-le comme la réponse du site, ou ajoutez-le à `custom_success_codes` pour recevoir le body malgré tout.
`705`	Le site a répondu `403`, généralement un blocage. Réduisez votre débit de requêtes et analysez la situation avant de réessayer.
`706`	Le site a répondu `429` et vous applique une limite de débit. Patientez et réduisez votre débit de requêtes.

Bloqué ou échoué

Code	Signification	Que faire
`503`	Crawlbase a reconnu une page de blocage ou de CAPTCHA.	Passez du Normal token au JavaScript token ; si vous êtes déjà sur JavaScript, patientez puis réessayez
`595`	L'élément `css_click_selector` est introuvable sur la page.	Corrigez le sélecteur ou ajoutez un repli comme `#start-button,body`
`599`	Erreur interne Crawlbase.	Réessayez avec un backoff ; envoyez le `rid` au support si le problème persiste
`5xx-7xx`	Tout autre code `5xx`, `6xx` ou `7xx` correspond à un échec interne ou propre au site. Aucun d'eux n'est facturé.	Réessayez avec un nombre de tentatives plafonné ; envoyez le `rid` au support si le problème persiste

Lire la réponse

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'])

Étapes suivantes

Gestion des erreurs

Modèles pour les retries, les files de messages morts et l'observabilité.

Limites de débit

Conseils spécifiques sur les 429 et la concurrence.