SERP-API-Fehler: Codes, Ursachen, Behebungen und Retries

Wie sieht eine Fehlerantwort aus?

Jeder Fehler hat denselben kleinen JSON-Body mit einem stabilen code und einer für Menschen lesbaren message. Verzweigen Sie in Ihrem Programm nach code und protokollieren Sie message für Menschen. Der HTTP-Status entspricht der obigen Tabelle.

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

Warum erhalte ich 400 invalid_parameter?

Ein erforderlicher Wert fehlt oder ein Wert liegt außerhalb der Liste, die die API akzeptiert. Übliche Ursachen sind ein leeres q, ein Engine-Name mit Tippfehler wie google-news statt google_news, ein page über 10 oder ein device anders als desktop oder mobile.

Das message nennt den fehlerhaften Parameter. Vergleichen Sie Ihre Anfrage mit der API-Referenz; es wird nichts berechnet, Sie können also korrigieren und sofort erneut senden.

Warum erhalte ich 401 invalid_api_key?

Der Schlüssel hat die API nicht erreicht oder ist ungültig. Prüfen Sie, dass der Header genau Authorization: Bearer YOUR_KEY lautet, mit einem Leerzeichen nach Bearer. Prüfen Sie außerdem, dass Ihre Umgebungsvariable in der Shell oder dem Dienst gesetzt ist, der den Code ausführt, nicht nur in Ihrem Terminal. Ein widerrufener Schlüssel schlägt weiterhin fehl: Erstellen Sie im Dashboard einen neuen.

Was soll ich bei 402 insufficient_credits tun?

Kaufen Sie ein Credit-Paket über Ihr Guthaben und senden Sie dann erneut. Ist das Guthaben zu niedrig, laden Sie zuerst mit Krypto auf; die minimale Aufladung beträgt 25 $. Lesen Sie credits_remaining aus GET https://serpcrypto.com/api/v1/credits vor einem großen Job, um nicht mittendrin zu stoppen: Dieser Aufruf ist kostenlos.

Wie gehe ich mit 429 concurrency_limit um?

Bremsen Sie, statt zu stoppen. Das Limit zählt gleichzeitig laufende Suchanfragen, nicht Suchanfragen pro Tag. Jedes Konto kann eine festgelegte Anzahl von Suchen gleichzeitig ausführen; das Limit wird in Ihrem Dashboard angezeigt und auf Anfrage erhöht. Lesen Sie concurrency_limit aus dem Credits-Endpoint und dimensionieren Sie Ihren Worker-Pool danach; die Seiten Python und Node.js zeigen einen Pool, der es nie überschreitet.

Wann werden 502 und 504 zurückgegeben?

502 search_failed bedeutet, dass die Suche für diese Anfrage nicht abgeschlossen werden konnte; 504 search_timeout bedeutet, dass sie nicht rechtzeitig abgeschlossen wurde. Beide sind kostenlos und beide lohnen einen erneuten Versuch. Warten Sie vor jedem neuen Versuch etwas länger, wie der Code unten, und geben Sie nach fünf Versuchen auf, damit ein hängender Job nicht endlos läuft.

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

Sollte mein HTTP-Timeout kurz oder lang sein?

Lang genug, damit eine Suche abgeschlossen werden kann: Eine Suche läuft live, setzen Sie Ihr Client-Timeout daher auf 60 bis 90 Sekunden statt auf wenige Sekunden. Ein Client, der zu früh aufgibt, sendet eine zweite Anfrage, während die erste noch läuft, was einen Parallelitäts-Slot verschwendet und, wenn beide erfolgreich sind, zwei Credits.