Errori della SERP API: codici, cause, soluzioni e retry

Come appare una risposta di errore?

Ogni errore ha lo stesso piccolo corpo JSON con un code stabile e un message leggibile. Nel tuo programma fai il branching su code e registra message per le persone. Lo status HTTP corrisponde alla tabella qui sopra.

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

Perché ricevo 400 invalid_parameter?

Manca un valore obbligatorio oppure un valore è fuori dall'elenco che l'API accetta. Le cause più comuni sono un q vuoto, un nome di motore con un errore di battitura come google-news invece di google_news, un page sopra 10, o un device diverso da desktop o mobile.

Il message indica il parametro in errore. Confronta la tua richiesta con la documentazione API; non viene addebitato nulla, quindi puoi correggere e reinviare subito.

Perché ricevo 401 invalid_api_key?

La chiave non è arrivata all'API, oppure non è valida. Controlla che l'header sia esattamente Authorization: Bearer YOUR_KEY, con uno spazio dopo Bearer. Controlla anche che la tua variabile d'ambiente sia impostata nella shell o nel servizio che esegue il codice, non solo nel tuo terminale. Una chiave revocata continua a fallire: creane una nuova nella dashboard.

Cosa devo fare per 402 insufficient_credits?

Acquista un pack di crediti dal tuo saldo, poi reinvia. Se il saldo è troppo basso, ricarica prima in criptovalute; la ricarica minima è 25 USD. Leggi credits_remaining da GET https://serpcrypto.com/api/v1/credits prima di un job importante per evitare di fermarti a metà: quella chiamata è gratuita.

Come gestisco 429 concurrency_limit?

Rallenta invece di fermarti. Il limite conta le ricerche in esecuzione nello stesso momento, non le ricerche al giorno. Ogni account può eseguire un numero fisso di ricerche contemporaneamente; il limite è indicato nella tua dashboard e viene aumentato su richiesta. Leggi concurrency_limit dall'endpoint dei crediti e dimensiona il tuo pool di worker su quel valore; le pagine Python e Node.js mostrano un pool che non lo supera mai.

Quando vengono restituiti 502 e 504?

502 search_failed significa che la ricerca non è riuscita per questa richiesta; 504 search_timeout significa che non è terminata in tempo. Entrambi sono gratuiti ed entrambi vale la pena riprovarli. Attendi un po' di più prima di ogni nuovo tentativo, come fa il codice qui sotto, e desisti dopo cinque tentativi così un job bloccato non entra in loop all'infinito.

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

Il mio timeout HTTP deve essere breve o lungo?

Abbastanza lungo da far terminare una ricerca: una ricerca gira live, quindi imposta il timeout del client su 60-90 secondi invece di pochi secondi. Un client che desiste troppo presto invia una seconda richiesta mentre la prima è ancora in corso, il che spreca uno slot di concorrenza e, se entrambe riescono, due crediti.