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

> Codes d'erreur de l'API SERP SerpCrypto : 400, 401, 402, 429, 502 et 504, ce qui les cause et comment les corriger ou les retenter.

- URL: https://serpcrypto.com/fr/docs/errors/
- Dernière mise à jour: 2026-10-22
- Éditeur: SerpCrypto (https://serpcrypto.com)

Six codes d'erreur, une règle : une erreur n'utilise jamais de crédit. Cette page indique ce qui déclenche chaque code, s'il faut retenter, et fournit le code de retry avec backoff exponentiel en Python et Node.js.

**Réponse rapide — Quelles erreurs de l'API SERP faut-il retenter, et les recherches échouées sont-elles facturées ?**

**SerpCrypto** ne facture jamais une erreur : seule une recherche réussie utilise 1 crédit. Retentez `429 concurrency_limit`, `502 search_failed` et `504 search_timeout` avec un backoff exponentiel. Ne retentez pas `400`, `401` ou `402` : corrigez d'abord le paramètre, la clé ou le solde. Les crédits coûtent à partir de 0,30 $US/1K requêtes et n'expirent jamais ; le paiement se fait en crypto, sans KYC.

## Que signifie chaque code d'erreur ?

Aucune ligne de ce tableau ne consomme de crédit. 1 crédit = 1 requête réussie, qui renvoie une page de résultats sur n'importe quel moteur pris en charge. Une requête qui échoue n'est pas facturée.

| HTTP | `code` | Cause | Que faire | Réessayer ? |
| --- | --- | --- | --- | --- |
| 400 | `invalid_parameter` | `q` est manquant, ou une valeur est en dehors de la liste autorisée | Corrigez la requête ; le message indique le paramètre concerné | Non |
| 401 | `invalid_api_key` | Aucune clé, une clé mal saisie ou une clé révoquée | Vérifiez le header ou `api_key` ; créez une nouvelle clé si nécessaire | Non |
| 402 | `insufficient_credits` | Le compte a 0 crédit | Achetez un pack depuis votre solde | Après l'achat |
| 429 | `concurrency_limit` | Plus de recherches simultanées que votre compte ne l'autorise | Attendez, réduisez le parallélisme ou demandez au support une limite plus élevée | Oui, avec backoff |
| 502 | `search_failed` | Le moteur ou la collecte a échoué pour cette requête | Relancez la même requête | Oui, avec backoff |
| 504 | `search_timeout` | Aucune réponse dans les délais | Relancez la même requête | Oui, avec backoff |

## À 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.

*Corps d'une réponse 402*

```json
{
  "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](https://serpcrypto.com/fr/docs/search/) ; 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](https://serpcrypto.com/fr/docs/python/) et [Node.js](https://serpcrypto.com/fr/docs/node/) 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.

*Python : réessayer les 429, 502 et 504 avec backoff exponentiel*

```python
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"])
```

*Node.js : la même logique avec fetch*

```javascript
// 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.

## Questions sur les erreurs

### Une recherche est-elle facturée si mon programme plante avant de lire la réponse ?

Oui, si l'API a bien exécuté la recherche et renvoyé un 200 : le crédit est consommé lorsque la recherche réussit, pas lorsque vous la lisez. C'est une raison de plus de définir un délai d'attente client suffisamment long.

### Les nouvelles tentatives coûtent-elles plus cher ?

Seule la tentative qui réussit consomme un crédit. Les tentatives échouées en 429, 502 ou 504 sont gratuites, donc une requête qui réussit à la troisième tentative coûte 1 crédit au total.

### Où signaler une erreur qui revient sans cesse ?

Écrivez à support@serpcrypto.com en joignant le `search_metadata.id` d'une recherche réussie ou l'heure, le moteur et les paramètres de celle qui échoue. Réponses par email sous 12 heures, 7 jours sur 7, y compris pour l'aide à l'intégration de l'API.

---

SerpCrypto: SerpCrypto est une API SERP pour les développeurs et les agents IA qui renvoie les résultats de recherche Google et Bing en JSON, payable en crypto sans envoi de pièce d'identité. Les crédits de recherche prépayés à partir de 0,30 $US/1K requêtes n'expirent jamais. Sans KYC — pas de pièce d'identité, pas de selfie, pas de documents. Payer en crypto.