> ## Documentation Index > Fetch the complete documentation index at: https://firecrawl-capy-docs-factual-copy-fixes.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # 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](https://github.com/firecrawl/firecrawl/issues) 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. ```json theme={null} { "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 | Solution | Réessayable | | - | - | - | - | - | | 400 | `Bad Request` / message de validation | Le corps de la requête ne respecte pas le 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 absent, mal formé ou utilise un schéma non pris en charge. | Fournissez une URL absolue en `http(s)://`. | Non | | 400 | `THIRD_PARTY_DATA_UNSUPPORTED_URL` | L'URL appartient à un site pris en charge par un provider de données tiers, mais ce provider ne fournit que la page propre d'un enregistrement (par exemple une page de profil), et non les sous-pages qui en dépendent. La réponse contient cette valeur dans `code`. | Effectuez l'extraction de la page propre à l'enregistrement plutôt que d'une sous-page ou d'une fiche produit qui en dépend. | Non | | 400 | `THIRD_PARTY_DATA_UNSUPPORTED_OPTION` | Cette URL ne peut être servie que par un provider de données tiers (par exemple un profil LinkedIn), et la requête définit une option que le provider ne prend pas en charge : `actions`, `profile`, `minAge`, `zeroDataRetention`, `lockdown`, `redactPII`, ou un format non pris en charge comme `screenshot` ou `branding`. `error` indique l'option en cause. La réponse contient cette valeur dans `code`. | Renvoyez la requête sans cette option. Si la politique de votre équipe impose la conservation zéro des données, ces URL ne peuvent pas être traitées. Consultez [URL routées via un provider](/fr/features/scrape#provider-routed-urls). | Non | | 401 | `Unauthorized: Invalid token` | La clé API est absente, mal formée ou révoquée. | Envoyez `Authorization: Bearer fc-...` avec une clé valide, disponible dans le [tableau de bord](https://www.firecrawl.dev/app/api-keys). | 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 effectuez une mise à niveau de votre offre. | Non | | 403 | `Forbidden` | La clé ne dispose pas des autorisations nécessaires pour ce point de terminaison ou cette fonctionnalité. | Utilisez une clé disposant de la portée obligatoire ou effectuez une mise à niveau de votre offre pour accéder à cette fonctionnalité. | Non | | 403 | `SCRAPE_PROMPT_INJECTION_DETECTED` | L’option `checkPromptInjection` a détecté une tentative d’injection de prompt dans le contenu de la page scrapée ; l’extraction a donc été annulée. | Examinez manuellement le contenu de la page. S'il s'agit d'un faux positif, relancez la requête sans `checkPromptInjection`. Voir [Détection des injections de prompt](/fr/features/llm-extract#prompt-injection-detection). | Non | | 403 | `THIRD_PARTY_DATA_NOT_ENABLED` | Le provider de données tierces associé à cette URL n'est pas activé pour votre organisation, par exemple parce qu'un administrateur de l'organisation l'a désactivé. La réponse contient cette valeur dans `code`. | Demandez à un administrateur de l'organisation d'activer le provider depuis sa page [Alexandria](/fr/features/alexandria), ou retirez-le de vos providers d'enrichissement. | Après son activation | | 403 | `THIRD_PARTY_DATA_ENRICHMENT_NOT_ENABLED` | L'URL correspond à un profil ou à une page d'entreprise LinkedIn, mais l'enrichissement est désactivé pour ce type de profil, ou aucun de vos providers d'enrichissement enregistrés ne peut la prendre en charge. La réponse contient cette valeur dans `code`, et `error` renvoie vers les paramètres d'enrichissement. | Demandez à un administrateur de l'organisation d'activer l'enrichissement et de sélectionner des providers dans les paramètres d'enrichissement. Voir [URL routées vers un provider](/fr/features/scrape#provider-routed-urls). | Après configuration | | 403 | `We apologize for the inconvenience but we do not support this site...` / `UNSUPPORTED_SITE` | Firecrawl n'effectue pas d'extraction sur ce site, et aucun provider de données tiers ne dessert cette URL. Certaines réponses contiennent également `UNSUPPORTED_SITE` dans `code`. | Utilisez une autre source pour ces données. Les clients Enterprise peuvent contacter l’équipe commerciale à propos de ce site. | Non | | 403 | `THIRD_PARTY_DATA_TERMS_REQUIRED` | Un provider [Alexandria](/fr/features/alexandria) exige que votre organisation accepte ses conditions avant de pouvoir exécuter la requête. Le provider n'a pas été exécuté. La réponse contient cette valeur dans `code`, ainsi que `requiresAction.url`. | Transmettez `requiresAction.url` à un administrateur de l'organisation, qui pourra y examiner et accepter les conditions. Les agents ne doivent jamais accepter les conditions de leur propre initiative. Une fois les conditions acceptées, renvoyez la même requête. | Après acceptation | | 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 | | 404 | `THIRD_PARTY_DATA_NOT_FOUND` | L'URL est servie par des providers de données tiers, et aucun d'entre eux ne possède d'enregistrement correspondant. Si plusieurs providers d'enrichissement sont configurés, ils ont tous été interrogés. Un provider sans enregistrement ne facture rien. La réponse contient cette valeur dans `code`. | Vérifiez que l’URL pointe vers un profil ou une page d’entreprise qui existe. L’ajout de providers d’enrichissement peut améliorer la couverture. | Non | | 408 | `Request Timeout` | Le chargement de la page a dépassé le délai d’expiration (`timeout`) de la requête. | Augmentez la valeur de `timeout`, simplifiez les actions ou utilisez `fastMode`. | Oui, avec un backoff exponentiel | | 409 | `Conflict` | L’état de la ressource empêche l’opération (par exemple, la ressource a déjà été supprimée). | Récupérez à nouveau l’état et résolvez les incohérences avant de réessayer. | Non | | 413 | `Payload Too Large` | Le corps de la requête dépasse la taille maximale autorisée. | Réduisez la charge utile (p. ex. un schéma plus court ou moins d’URL par lot). | Non | | 422 | `Unprocessable Entity` / erreur de schéma d'extraction | Le schéma ne respecte pas la spécification JSON Schema, 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` | Le nombre de requêtes dépasse la limite par minute de votre offre. | Espacez vos requêtes et réessayez après le délai indiqué (en secondes) par `Retry-After`. Consultez [Limites de débit](/fr/rate-limits). | Oui, avec backoff exponentiel | | 429 | `Concurrency limit reached` | La limite de navigateurs simultanés autorisés par votre offre est atteinte. | Attendez la fin des tâches en cours, réduisez la concurrence ou effectuez une mise à niveau de votre offre. | Oui, avec un backoff exponentiel | | 500 | `Internal Server Error` | Erreur non gérée côté serveur. | Réessayez avec un backoff exponentiel. Si le problème persiste, contactez l’assistance en indiquant l’identifiant de la requête. | Oui, avec un backoff exponentiel | | 502 | `Bad Gateway` | Le proxy ou le processus de traitement en amont a renvoyé une réponse invalide. | Réessayez avec un backoff exponentiel. | Oui, avec un backoff exponentiel | | 503 | `Service Unavailable` | Le service ne peut temporairement pas traiter la requête. | Réessayez avec un backoff exponentiel. | Oui, avec un backoff exponentiel | | 504 | `Gateway Timeout` | La requête a dépassé le délai d'expiration de la passerelle (généralement lors de crawls de longue durée). | Utilisez plutôt les points de terminaison asynchrones crawl/batch et interrogez régulièrement l’état de l’opération. | 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`](/fr/features/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](/fr/api-reference/endpoint/agent-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 [support@firecrawl.com](mailto:support@firecrawl.com) 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](/fr/api-reference/endpoint/agent-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 `stopReason: "credit_limit_reached"`, 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. La réponse peut également inclure un résultat `partial`, fourni dans la mesure du possible. Vérifiez `stopReason` plutôt que de vous baser sur le texte de l’erreur, et consultez [Gérer les arrêts dus à la limite de crédits](/fr/features/agent#handling-credit-limit-stops) pour savoir comment exploiter un résultat partiel et poursuivre l’exécution. 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 Python theme={null} 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 ``` ```js Node theme={null} const RETRYABLE_STATUSES = new Set([408, 429, 500, 502, 503, 504]); async function requestWithRetry(url, init = {}, maxAttempts = 5) { for (let attempt = 0; attempt < maxAttempts; attempt++) { const resp = await fetch(url, init); if (resp.ok || !RETRYABLE_STATUSES.has(resp.status)) return resp; // Respecte Retry-After lorsqu'il est présent, sinon applique un backoff exponentiel avec jitter. const retryAfter = resp.headers.get('Retry-After'); const delayMs = retryAfter ? Number(retryAfter) * 1000 : Math.min(2 ** attempt, 30) * 1000 + Math.random() * 1000; await new Promise((r) => setTimeout(r, delayMs)); } } ``` ```bash cURL theme={null} # Boucle shell simple avec backoff exponentiel pour les codes pouvant être retentés. attempt=0 max=5 until response=$(curl -sS -w "\n%{http_code}" -X POST "https://api.firecrawl.dev/v2/scrape" \ -H "Authorization: Bearer $FIRECRAWL_API_KEY" \ -H "Content-Type: application/json" \ -d '{"url":"https://example.com"}'); do status=$(printf '%s' "$response" | tail -n1) case "$status" in 408|429|500|502|503|504) attempt=$((attempt+1)) [ "$attempt" -ge "$max" ] && break sleep $((2 ** attempt)) ;; *) break ;; esac done echo "$response" ```

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](/fr/rate-limits). Respectez toujours l’en-tête `Retry-After` lorsqu’il est présent, plutôt que de réessayer immédiatement. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.