Erreurs de l'API SERP : codes, causes, corrections et retries

À quoi ressemble une réponse d'erreur ?

Chaque erreur renvoie le même petit corps JSON, avec un code stable et un message lisible par un humain. Branchez votre programme sur code et journalisez message pour les humains. Le statut HTTP correspond au tableau ci-dessus.

{
  "error": {
    "code": "insufficient_credits",
    "message": "Your account has no search credits left."
  }
}

Pourquoi est-ce que j'obtiens 400 invalid_parameter ?

Une valeur obligatoire est manquante ou une valeur est en dehors de la liste acceptée par l'API. Les causes habituelles sont un q vide, un nom de moteur mal orthographié comme google-news au lieu de google_news, un page supérieur à 10, ou un device autre que desktop ou mobile.

Le message indique le paramètre en cause. Comparez votre requête avec la référence de l'API ; rien n'est facturé, vous pouvez donc corriger et renvoyer immédiatement.

Pourquoi est-ce que j'obtiens 401 invalid_api_key ?

La clé n'a pas atteint l'API, ou elle n'est pas valide. Vérifiez que le header est exactement Authorization: Bearer YOUR_KEY, avec un espace après Bearer. Vérifiez aussi que votre variable d'environnement est définie dans le shell ou le service qui exécute le code, pas seulement dans votre terminal. Une clé révoquée continue d'échouer : créez-en une nouvelle dans le dashboard.

Que faire face à 402 insufficient_credits ?

Achetez un pack de crédits depuis votre solde, puis renvoyez la requête. Si le solde est trop bas, rechargez d'abord en crypto ; la recharge minimale est de 25 $US. Lisez credits_remaining depuis GET https://serpcrypto.com/api/v1/credits avant une tâche importante pour éviter de vous arrêter en cours de route : cet appel est gratuit.

Comment gérer 429 concurrency_limit ?

Ralentissez plutôt que de vous arrêter. La limite compte les recherches exécutées en même temps, pas les recherches par jour. Chaque compte peut lancer un nombre défini de recherches en même temps ; la limite est indiquée dans votre tableau de bord et augmentée sur demande. Lisez concurrency_limit depuis l'endpoint des crédits et dimensionnez votre pool de workers en conséquence ; les pages Python et Node.js montrent un pool qui ne la dépasse jamais.

Quand les 502 et 504 sont-ils renvoyés ?

502 search_failed signifie que la recherche n'a pas pu être menée à bien pour cette requête ; 504 search_timeout signifie qu'elle ne s'est pas terminée dans les délais. Les deux sont gratuits et méritent tous deux une nouvelle tentative. Attendez un peu plus longtemps avant chaque nouvel essai, comme le fait le code ci-dessous, et abandonnez après cinq tentatives pour qu'une tâche bloquée ne boucle pas indéfiniment.

import os
import random
import time

import requests

API_URL = "https://serpcrypto.com/api/v1/search"
RETRYABLE = {429, 502, 504}


def search(params, max_attempts=5):
    headers = {"Authorization": "Bearer " + os.environ["SERPCRYPTO_API_KEY"]}
    for attempt in range(1, max_attempts + 1):
        r = requests.get(API_URL, params=params, headers=headers, timeout=90)
        if r.status_code == 200:
            return r.json()
        error = r.json().get("error", {})
        if r.status_code not in RETRYABLE or attempt == max_attempts:
            raise RuntimeError(f"{r.status_code} {error.get('code')}: {error.get('message')}")
        # exponential backoff with jitter: about 1 s, 2 s, 4 s, 8 s
        time.sleep(2 ** (attempt - 1) + random.random())
    raise RuntimeError("unreachable")


print(search({"q": "solar panel installers", "gl": "au", "hl": "en"})["search_metadata"])

// retry.mjs — Node.js 18+
const API_URL = "https://serpcrypto.com/api/v1/search";
const RETRYABLE = new Set([429, 502, 504]);
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

export async function search(params, maxAttempts = 5) {
  const url = `${API_URL}?${new URLSearchParams(params)}`;
  const headers = { Authorization: `Bearer ${process.env.SERPCRYPTO_API_KEY}` };
  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    const res = await fetch(url, { headers });
    if (res.ok) return res.json();
    const body = await res.json().catch(() => ({}));
    const code = body.error?.code ?? "unknown";
    if (!RETRYABLE.has(res.status) || attempt === maxAttempts) {
      throw new Error(`${res.status} ${code}: ${body.error?.message ?? ""}`);
    }
    // exponential backoff with jitter: about 1 s, 2 s, 4 s, 8 s
    await sleep(1000 * 2 ** (attempt - 1) + Math.random() * 1000);
  }
  throw new Error("unreachable");
}

console.log((await search({ q: "solar panel installers", gl: "au", hl: "en" })).search_metadata);

Mon timeout HTTP doit-il être court ou long ?

Assez long pour qu'une recherche aboutisse : une recherche s'exécute en direct, alors réglez le timeout de votre client sur 60 à 90 secondes plutôt que sur quelques secondes. Un client qui abandonne trop tôt envoie une seconde requête alors que la première tourne encore, ce qui gaspille un slot de concurrence et, si les deux réussissent, deux crédits.