Erreurs

Toutes les réponses d’erreur de Firecrawl utilisent le même format JSON. Recherchez la valeur error (ou l’état HTTP) dans le tableau ci-dessous pour en connaître la cause, la solution et savoir si la requête peut être relancée sans risque.

Toutes les réponses non-2xx renvoient du JSON avec success: false à la racine, ainsi qu’une chaîne error. Certains points de terminaison incluent des champs supplémentaires (details, code) lorsque plus de contexte est disponible.

{  "success": false,  "error": "Unauthorized: Invalid token",  "details": "Optional structured details (only present on some errors)"}

Pour les réponses 429, Firecrawl inclut un en-tête Retry-After (en secondes) lorsqu’il est disponible — attendez au moins ce délai avant de réessayer.

Erreurs spécifiques à /agent et à ses points de terminaison d’état, de trace, d’instantané et d’annulation. Les points de terminaison de trace et d’instantané relaient tels quels les corps d’erreur en amont. Ces deux points de terminaison peuvent donc répondre avec un corps qui omet le champ success décrit ci-dessus ; basez-vous sur l’état HTTP et la chaîne error.

Une exécution qui atteint sa limite maxCredits ne renvoie pas d’erreur HTTP. Elle se termine avec une tâche en échec. Interrogez le point de terminaison d’état : vous obtenez status: "failed", avec un message d’erreur indiquant la limite de crédits, aucune data et creditsUsed: 0, car les exécutions en échec ne sont pas facturées. Dans la trace, le même résultat apparaît sous la forme d’un événement run.finished avec outcome: "credit_limit_reached".

Les événements de trace Terminal et error.occurred contiennent un objet error structuré dont le code correspond à l’une des cinq valeurs suivantes. Ils contiennent également un booléen retryable, à traiter de la même manière que la colonne Réessayable ci-dessus.

Considérez la colonne réessayable comme la référence ; ne vous basez pas uniquement sur le code d’état HTTP. Le modèle ci-dessous utilise un backoff exponentiel avec jitter et respecte Retry-After pour les réponses 429.

import timeimport randomimport requestsRETRYABLE_STATUSES = {408, 429, 500, 502, 503, 504}def request_with_retry(method, url, headers=None, json=None, max_attempts=5):    for attempt in range(max_attempts):        resp = requests.request(method, url, headers=headers, json=json)        if resp.status_code < 400 or resp.status_code not in RETRYABLE_STATUSES:            return resp        # Respecte Retry-After lorsqu'il est présent, sinon applique un backoff exponentiel avec jitter.        retry_after = resp.headers.get("Retry-After")        delay = float(retry_after) if retry_after else min(2 ** attempt, 30) + random.random()        time.sleep(delay)    return resp

Les réponses 429 constituent l’erreur réessayable la plus courante. Les limites de débit et de concurrence propres à chaque offre sont documentées dans Limites de débit. Respectez toujours l’en-tête Retry-After lorsqu’il est présent, plutôt que de réessayer immédiatement.