Skip to main content
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.
Ce récapitulatif couvre les erreurs que la plupart des agents et clients rencontreront. Il n’est pas exhaustif — si vous recevez une erreur qui n’est pas répertoriée ici, veuillez ouvrir une issue afin que nous puissions la documenter.

Format de la réponse d’erreur

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.

Erreurs

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.

Agent

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".

Codes d’erreur de trace

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.

Conseils de réessai

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.

Réponses 429

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.