Passer au contenu principal
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)"
}
ChampTypeDescription
successbooleanToujours false en cas d’erreur.
errorstringMessage d’erreur compréhensible par un humain. Utilisez-le pour retrouver la ligne ci-dessous.
detailsanyFacultatif. Erreurs de validation structurées par champ, le cas échéant.

​
Erreurs

HTTPerror (message typique)CauseRemèdeRéessayable
400Bad Request / message de validationLe 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
400Invalid URLLe champ url est manquant, mal formé ou utilise un protocole non pris en charge.Fournissez une URL absolue http(s)://.Non
401Unauthorized: Invalid tokenLa clé d’API est manquante, mal formée ou révoquée.Envoyez Authorization: Bearer fc-... avec une clé valide depuis le dashboard.Non
402Payment Required: Insufficient creditsLes crédits de l’offre sont épuisés ou la facturation n’est pas configurée.Rechargez des crédits, activez la recharge automatique ou passez à une offre supérieure.Non
403ForbiddenLa 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
404Not FoundL’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
408Request TimeoutLa 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
409ConflictLa 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
413Payload Too LargeLe 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
422Unprocessable Entity / erreur de schéma d’extractionLe 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
429Rate limit exceededTrop de requêtes pour la limite par minute de votre offre.Attendez puis réessayez après Retry-After secondes. Voir limites de débit.Oui, avec backoff exponentiel
429Concurrency limit reachedLa 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
500Internal Server ErrorDé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
502Bad GatewayLe proxy ou le worker en amont a renvoyé une réponse invalide.Réessayez avec un backoff exponentiel.Oui, avec backoff exponentiel
503Service UnavailableLe service est temporairement incapable de traiter la requête.Réessayez avec un backoff exponentiel.Oui, avec backoff exponentiel
504Gateway TimeoutLa 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.

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