--- title: "Dépannage de l'API Surfer" description: "Vous avez des problèmes avec les appels de l'API Surfer ? Consultez les problèmes les plus courants pour trouver rapidement une solution." url: https://docs.surferseo.com/fr/articles/8196553-depannage-de-l-api-surfer collection: "API" updated: 2026-10-06 language: fr alternates: [en, de] --- # Dépannage de l'API Surfer Vous avez des problèmes avec les appels de l'API Surfer ? Consultez les problèmes les plus courants pour trouver rapidement une solution. ## Tableau de référence :

Code	Nom	Cause en français clair	Correction
400	Mauvaise requête	Erreur de syntaxe dans votre JSON (virgule manquante, mauvais crochet)	Validez la charge utile de votre requête
401	Non autorisé	Clé API manquante ou incorrecte, ou nom d'en-tête incorrect	Utilisez l'en-tête `API-KEY` avec la clé du propriétaire du compte
403	Interdit	Clé valide, mais cet outil ou ce point de terminaison spécifique n'est pas activé sur votre compte ; l'accès à l'API ne déverrouille pas automatiquement tous les outils (par exemple, Audit, Analyse SERP ou Éditeur de contenu peuvent nécessiter un Add-on ou une offre de niveau supérieur)	Vérifiez si la fonctionnalité nécessite un Add-on séparé ou une mise à niveau de l'offre
404	Non trouvé	URL de base incorrecte, ou l'ID de ressource n'existe pas / n'appartient pas à votre compte	Vérifiez l'URL et l'ID
406	Non acceptable	Format de réponse non pris en charge demandé (V2 uniquement)	Omettez l'en-tête `Accept`, ou définissez-le sur `application/json`
409	Conflit	Conflit de clé d'idempotence (V2 uniquement)	Utilisez une clé d'idempotence unique par requête
413	Contenu trop volumineux	Le corps de la requête dépasse la limite de taille	Réduisez l'entrée (AI Detector max : 100 000 caractères)
415	Type de média non pris en charge	En-tête `Content-Type` incorrect	Définissez `Content-Type: application/json`
422	Quota dépassé	Vous avez épuisé les crédits de votre offre pour cet outil	Attendez la réinitialisation de la facturation ou effectuez une mise à niveau
422	Entité non traitable	Paramètre obligatoire manquant ou type de données incorrect	Vérifiez les champs obligatoires du point de terminaison dans la documentation de l'API
429	Limite de débit dépassée	Trop de requêtes par seconde/minute	Vérifiez `x-ratelimit-reset` pour savoir quand la fenêtre se réinitialise, puis réessayez avec un délai d'attente
500	Erreur interne du serveur	Problème côté serveur, ou requête CE vide jamais ouverte	Réessayez après quelques minutes ; si le problème persiste, contactez le support

* * * ## Problèmes que vous pourriez rencontrer lors de l'utilisation de l'API : ### 1\. La requête génère une réponse HTML générique L'URL que vous avez spécifiée dans la requête est invalide et ne correspond pas à un point de terminaison API. ### 2\. Toute requête génère une erreur 401 Non autorisé avec le message « Access Denied » La clé API spécifiée est incorrecte ou manquante, ou votre offre ne prend pas en charge les requêtes API. Rappelez-vous que l'en-tête « Key » doit être explicitement nommé « API-KEY ». ### 3\. Toute requête génère une erreur 403 Interdit avec le message « Access Denied » Votre offre actuelle ne prend pas en charge l'API. Veuillez vérifier votre offre d'abonnement actuelle dans les paramètres de l'application et la comparer aux offres proposant l'API sur notre [page de tarification](https://surferseo.com/pricing/). ### 4\. Les requêtes POST génèrent une erreur 422 Entité non traitable avec le message « Quota exceeded » - **Audit et Éditeur de contenu :** Cela signifie que vous avez atteint la limite d'utilisation de cet outil au cours de votre période de facturation actuelle. - **Analyse SERP :** Vous avez dépassé votre quota quotidien (100 requêtes/jour par défaut). Vous pouvez soit attendre, soit contacter notre équipe commerciale pour étendre les limites avec une offre Enterprise personnalisée. ### 5\. Les requêtes POST génèrent une erreur 400 Bad Request avec le message « Internal server error » Votre requête contient une erreur de syntaxe, par exemple une virgule manquante. ### 6\. Les requêtes POST génèrent une erreur 422 Unprocessable Entity avec un message JSON Votre requête ne contient probablement pas les paramètres requis (comme des mots-clés manquants), ou elle est malformée (une chaîne a été fournie au lieu d'un tableau). ### 7\. Les requêtes GET de contenu CE génèrent une erreur 500 Internal Server Error Cela signifie que la requête n'a pas de contenu stocké. Il s'agit très probablement d'une requête vide, jamais ouverte via l'application. ### 8\. Les requêtes GET search\_results de l'Analyse SERP génèrent une erreur 404 Not found avec le message « Not found. » L'ID que vous avez spécifié dans l'URL de votre requête est incorrect, ou cet ID n'appartient pas au compte associé à cette clé API. ### 9\. Les requêtes GET search\_results de l'Analyse SERP génèrent une réponse 200 OK, mais la plupart ou certaines lignes contiennent des chaînes vides Cela signifie que la requête n'a pas terminé tous les calculs nécessaires. Vous pouvez consulter la 3ᵉ colonne, « state », pour voir l'état de chaque crawl concurrent. Comme pour les requêtes classiques : - « completed » : le crawl s'est déroulé avec succès ; les données présentes sont basées sur le contenu qui nous a été fourni (ne contient pas de valeurs vides, la valeur par défaut est « 0 ») - « scheduled » : le crawl est toujours en cours de traitement (contient des chaînes vides) - « failed » : le crawl s'est terminé sans succès, le plus souvent parce que nous avons été bloqués ou que le délai d'attente a été dépassé lors de l'accès à cette URL (contient des chaînes vides) ### 10\. Les requêtes GET prominent\_terms de l'Analyse SERP génèrent une erreur 404 Not found avec le message « Not found » L'ID que vous avez spécifié dans l'URL de votre requête est incorrect, ou cet ID n'appartient pas au compte associé à cette clé API. Si vous êtes certain que l'ID est correct, alors soit : - cette requête est toujours en cours de traitement (indiquée comme « scheduled » par le point de terminaison exports/csv/serp\_analyzer) ; ou - nous n'avons pas pu trouver de termes marquants pour cette requête, le plus souvent en raison d'un contenu écrit insuffisant chez les concurrents SERP. ### 11\. TOUTE requête aboutissant à une erreur 429 Too Many Requests Vous avez dépassé la limite de débit. Tous les points de terminaison ont une limite par défaut de **10 requêtes/s**, **sauf pour le lot SERP : 10 requêtes/min**. Vérifiez l'en-tête `Retry-After` de la réponse pour savoir combien de temps attendre, puis réessayez. Pour les flux de travail automatisés, implémentez un backoff exponentiel. Si vous atteignez régulièrement cette limite, examinez votre fréquence de requêtes ou contactez le support. ### 12\. POST aboutissant à une erreur 406 Not Acceptable À noter : ceci concerne uniquement la v2. Le format de réponse demandé n'est pas disponible. Cela signifie généralement qu'un en-tête `Accept` a été inclus avec une valeur non prise en charge. Supprimez-le ou définissez-le sur `application/json`. ### 13\. TOUTE requête → 404 Not Found (mauvaise URL de base) À noter : ceci est différent de la [404 spécifique à l'Analyse SERP](https://docs.surferseo.com/en/articles/8196553-surfer-api-troubleshooting.md#heading-7-8-get-serp-analyzer-search-results-requests-result-in-404-not-found-with-not-found-message) ci-dessus. Si vous recevez une 404 sur un point de terminaison non SERP, votre URL de base est probablement incorrecte. Assurez-vous d'appeler : - v1 : `https://app.surferseo.com/api/v1/` - v2 : `https://app.surferseo.com/api/v2/` Et non `api.surferseo.com`, `surferseo.com/api/…` ou toute autre variante. ### 14\. POST → 413 Content Too Large Le corps de votre requête dépasse la limite de taille. C'est le plus courant sur l'AI Detector (max 100 000 caractères) et l'Humanizer (minimum 128 caractères, mais les très grandes entrées peuvent être rejetées). Réduisez votre entrée et réessayez. ### 15\. TOUTE requête → 415 Unsupported Media Type Votre requête utilise un en-tête `Content-Type` non pris en charge. Toutes les requêtes doivent utiliser `Content-Type: application/json`. * * * ## Ressources supplémentaires : [Introduction à l'API Surfer](https://docs.surferseo.com/en/articles/5700335-surfer-api-introduction.md) [Documentation de l'API Surfer (v1)](https://app.surferseo.com/api/v1/docs#section/Introduction) [Documentation de l'API Surfer (v2)](https://app.surferseo.com/api/v2/docs) [Exemples d'utilisation de l'API Surfer](https://docs.surferseo.com/en/articles/8201326-surfer-api-examples-of-use.md)