SERP API-fouten: codes, oorzaken, oplossingen en retries

Hoe ziet een foutantwoord eruit?

Elke fout heeft dezelfde kleine JSON-body met een stabiele code en een leesbare message. Vertak in je programma op code en log message voor mensen. De HTTP-status komt overeen met de tabel hierboven.

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

Waarom krijg ik 400 invalid_parameter?

Een vereiste waarde ontbreekt of een waarde valt buiten de lijst die de API accepteert. De gebruikelijke oorzaken zijn een lege q, een engine-naam met een typefout zoals google-news in plaats van google_news, een page boven 10, of een device anders dan desktop of mobile.

De message noemt de parameter die fout is. Vergelijk je aanvraag met de API-referentie; er wordt niets in rekening gebracht, dus je kunt meteen corrigeren en opnieuw versturen.

Waarom krijg ik 401 invalid_api_key?

De API-sleutel bereikte de API niet, of is niet geldig. Controleer dat de header precies Authorization: Bearer YOUR_KEY is, met een spatie na Bearer. Controleer ook dat je environment variable is ingesteld in de shell of service die de code uitvoert, niet alleen in je terminal. Een ingetrokken API-sleutel blijft falen: maak een nieuwe aan in het dashboard.

Wat moet ik doen aan 402 insufficient_credits?

Koop een creditpack vanuit je saldo en verstuur opnieuw. Is je saldo te laag, waardeer dan eerst op met crypto; de minimale opwaardering is US$ 25. Lees credits_remaining uit GET https://serpcrypto.com/api/v1/credits vóór een grote klus om te voorkomen dat je halverwege moet stoppen: die call is gratis.

Hoe ga ik om met 429 concurrency_limit?

Doe het rustiger aan in plaats van te stoppen. De limiet telt zoekopdrachten die tegelijk lopen, niet zoekopdrachten per dag. Elk account kan een vast aantal zoekopdrachten tegelijk uitvoeren; de limiet staat in je dashboard en wordt op aanvraag verhoogd. Lees concurrency_limit uit het credits-endpoint en stem je worker pool daarop af; de Python- en Node.js-pagina's tonen een pool die die nooit overschrijdt.

Wanneer worden 502 en 504 teruggegeven?

502 search_failed betekent dat de zoekopdracht niet kon worden voltooid voor deze aanvraag; 504 search_timeout betekent dat die niet op tijd werd voltooid. Beide zijn gratis en beide zijn het waard om opnieuw te proberen. Wacht iets langer voor elke nieuwe poging, zoals de code hieronder doet, en geef na vijf pogingen op zodat een vastgelopen job niet eindeloos blijft loopen.

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

Moet mijn HTTP-timeout kort of lang zijn?

Lang genoeg om een zoekopdracht te laten afronden: een zoekopdracht loopt live, dus zet je client-timeout op 60 tot 90 seconden in plaats van een paar seconden. Een client die te vroeg opgeeft, stuurt een tweede aanvraag terwijl de eerste nog loopt, wat een concurrency-slot verspilt en, als beide slagen, twee credits.