Dépannage de l'API Surfer

Tableau de référence :

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.

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

Documentation de l'API Surfer (v1)

Documentation de l'API Surfer (v2)

Exemples d'utilisation de l'API Surfer