Erreurs

Chaque code d’erreur de l’API, sa cause, comment y remédier et s’il faut réessayer.

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.

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

Champ	Type	Description
success	boolean	Toujours false en cas d’erreur.
error	string	Message d’erreur compréhensible par un humain. Utilisez-le pour retrouver la ligne ci-dessous.
details	any	Facultatif. Erreurs de validation structurées par champ, le cas échéant.

​

Erreurs

HTTP	error (message typique)	Cause	Remède	Réessayable
400	Bad Request / message de validation	Le corps de la requête n’a pas passé la validation du schéma (champs manquants ou invalides).	Corrigez le payload de la requête à l’aide de la référence du point de terminaison. Consultez details pour identifier les champs en cause.	Non
400	Invalid URL	Le champ url est manquant, mal formé ou utilise un protocole non pris en charge.	Fournissez une URL absolue http(s)://.	Non
401	Unauthorized: Invalid token	La clé d’API est manquante, mal formée ou révoquée.	Envoyez Authorization: Bearer fc-... avec une clé valide depuis le dashboard.	Non
402	Payment Required: Insufficient credits	Les crédits de l’offre sont épuisés ou la facturation n’est pas configurée.	Activez le paiement à l’usage ou passez à une offre supérieure.	Non
403	Forbidden	La clé ne dispose pas des autorisations nécessaires pour ce point de terminaison ou cette fonctionnalité.	Utilisez une clé avec le scope requis, ou passez à l’offre qui donne accès à cette fonctionnalité.	Non
403	SCRAPE_PROMPT_INJECTION_DETECTED	Le mode JSON avec checkPromptInjection: true a détecté une tentative d’injection de prompt dans le contenu de la page scrapée, l’extraction a donc été interrompue.	Examinez manuellement le contenu de la page. S’il s’agit d’un faux positif, réessayez sans checkPromptInjection. Voir détection des injections de prompt.	Non
404	Not Found	L’ID de tâche, la ressource ou le chemin du point de terminaison n’existe pas.	Vérifiez l’ID de la ressource et l’URL du point de terminaison.	Non
408	Request Timeout	La page a mis plus de temps à charger que le timeout de la requête.	Augmentez timeout, simplifiez les actions ou utilisez fastMode.	Oui, avec backoff exponentiel
409	Conflict	La ressource est dans un état qui empêche l’opération (par ex. déjà supprimée).	Récupérez à nouveau l’état et remettez-le en cohérence avant de réessayer.	Non
413	Payload Too Large	Le corps de la requête a dépassé la taille maximale autorisée.	Réduisez le payload (par ex. schéma plus court, moins d’URL par batch).	Non
422	Unprocessable Entity / erreur de schéma d’extraction	Le schéma est un JSON Schema invalide, ou le modèle n’a pas pu produire un résultat conforme.	Validez le schéma ; assouplissez les champs obligatoires ; essayez un autre model.	Parfois
429	Rate limit exceeded	Trop de requêtes pour la limite de débit par minute de votre offre.	Attendez puis réessayez après Retry-After secondes. Voir limites de débit.	Oui, avec backoff exponentiel
429	Concurrency limit reached	La limite de concurrence du browser pour votre offre est atteinte.	Attendez que les tâches en cours se terminent, réduisez la concurrence ou passez à une offre supérieure.	Oui, avec backoff exponentiel
500	Internal Server Error	Défaillance non gérée côté serveur.	Réessayez avec un backoff exponentiel. Si le problème persiste, contactez le support avec l’ID de la requête.	Oui, avec backoff exponentiel
502	Bad Gateway	Le proxy ou le worker en amont a renvoyé une réponse invalide.	Réessayez avec un backoff exponentiel.	Oui, avec backoff exponentiel
503	Service Unavailable	Le service est temporairement incapable de traiter la requête.	Réessayez avec un backoff exponentiel.	Oui, avec backoff exponentiel
504	Gateway Timeout	La requête a dépassé le timeout de la passerelle (généralement pour les crawls longs).	Utilisez plutôt les points de terminaison asynchrones de crawl/batch et interrogez l’état.	Oui, avec backoff exponentiel

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.

HTTP	error (message typique)	Cause	Solution	Réessayable
400	Invalid job ID format. Job ID must be a valid UUID.	Le segment de chemin jobId n’est pas un UUID.	Transmettez l’id renvoyé par POST /v2/agent.	Non
400	Invalid snapshot ID	Le segment de chemin snapshotId est mal formé.	Utilisez un snapshotId issu d’un événement de trace artifact.updated événement de trace.	Non
400	Trace is only available for Spark 2 extracts	La tâche est antérieure à Spark 2, qui enregistre les traces.	Il n’y a rien à faire pour cette tâche. Chaque nouvelle exécution s’effectue sur spark-2 et comporte une trace.	Non
400	Snapshots are only available for Spark 2 extracts	La tâche est antérieure à Spark 2, qui enregistre les instantanés.	Il n’y a rien à faire pour cette tâche. Chaque nouvelle exécution s’effectue sur spark-2 et comporte des instantanés.	Non
400	Your team has zero data retention enabled. This is not supported on extract.	Les exécutions d’agent ne sont pas disponibles pour une équipe soumise à la rétention zéro des données.	Contactez [e-mail] pour activer cette fonctionnalité pour votre équipe.	Non
404	Agent job not found	L’ID de tâche n’existe pas ou appartient à une autre équipe.	Vérifiez l’ID de tâche et utilisez une clé de l’équipe ayant démarré l’exécution.	Non
404	Snapshot not found	Aucun instantané avec cet ID n’appartient à cette tâche.	Récupérez de nouveau la trace et utilisez un snapshotId actuel issu d’un événement de trace artifact.updated événement de trace.	Non
409	Agent already finished	L’annulation a été demandée pour une exécution ayant déjà atteint un état terminal.	Interrogez plutôt GET /v2/agent/{jobId} pour obtenir le résultat.	Non
409	Agent is already cancelled	L’annulation a été demandée pour une exécution déjà en cours d’annulation.	Interrogez GET /v2/agent/{jobId}. Une exécution annulée renvoie failed avec un message d’annulation.	Non
500	Failed to passthrough agent request.	Le service d’agent a rejeté la tâche lors de sa soumission.	Réessayez avec un backoff exponentiel. Si le problème persiste, contactez le support en indiquant l’ID de requête.	Oui, avec backoff exponentiel

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.

code	Signification et solution
cancelled	Vous avez annulé l’exécution. Démarrez-en une nouvelle si vous souhaitez recommencer.
credit_limit_reached	L’exécution a atteint son plafond maxCredits. Augmentez maxCredits ou affinez le prompt afin que l’exécution nécessite moins de travail.
parent_finished	Un sous-agent s’est arrêté parce que l’agent qui l’a lancé s’est terminé avant lui. Consultez l’événement terminal de l’agent parent pour connaître la véritable cause.
refused	L’agent a refusé la tâche. Reformulez le prompt ou limitez-le aux URL pour lesquelles vous êtes autorisé à collecter des données.
internal	Une erreur inattendue s’est produite lors de l’exécution. Réessayez l’exécution ; si le problème persiste, contactez le support en indiquant l’ID de tâche.

​

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.

Python

import time
import random
import requests

RETRYABLE_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

​

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.