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

> Codici di errore della SERP API di SerpCrypto: 400, 401, 402, 429, 502 e 504, le cause, come risolverli e perché nessun errore consuma un credito.

- URL: https://serpcrypto.com/it/docs/errors/
- Ultimo aggiornamento: 2026-10-22
- Editore: SerpCrypto (https://serpcrypto.com)

Sei codici di errore, una regola: un errore non consuma mai un credito. Questa pagina spiega cosa attiva ciascun codice, se riprovare, e fornisce il codice di retry con backoff esponenziale in Python e Node.js.

**Risposta rapida — Quali errori della SERP API dovrei riprovare, e le ricerche fallite vengono addebitate?**

**SerpCrypto** non addebita mai un errore: solo una ricerca riuscita consuma 1 credito. Riprova `429 concurrency_limit`, `502 search_failed` e `504 search_timeout` con backoff esponenziale. Non riprovare `400`, `401` o `402`: correggi prima il parametro, la chiave o il saldo. I crediti costano da 0,30 USD/1K ricerche e non scadono mai; il pagamento è in criptovalute, senza KYC.

## Cosa significa ciascun codice di errore?

Nessuna riga di questa tabella usa un credito. 1 credito = 1 richiesta di ricerca andata a buon fine, che restituisce una pagina di risultati su qualsiasi motore supportato. Una richiesta non riuscita non viene addebitata.

| HTTP | `code` | Causa | Cosa fare | Riprovare? |
| --- | --- | --- | --- | --- |
| 400 | `invalid_parameter` | `q` manca, oppure un valore è fuori dall'elenco consentito | Correggi la richiesta; il messaggio indica il parametro | No |
| 401 | `invalid_api_key` | Nessuna chiave, una chiave scritta male o una chiave revocata | Controlla l'header o `api_key`; crea una nuova chiave se serve | No |
| 402 | `insufficient_credits` | L'account ha 0 crediti | Acquista un pack dal tuo saldo | Dopo l'acquisto |
| 429 | `concurrency_limit` | Più ricerche contemporanee di quante ne consenta il tuo account | Attendi, riduci il parallelismo o chiedi al supporto un limite più alto | Sì, con backoff |
| 502 | `search_failed` | Il motore o la raccolta non è riuscito per questa richiesta | Riprova la stessa richiesta | Sì, con backoff |
| 504 | `search_timeout` | Nessuna risposta in tempo | Riprova la stessa richiesta | Sì, con backoff |

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

*Corpo di una risposta 402*

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

*Python: riprova 429, 502 e 504 con backoff esponenziale*

```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 stessa logica con 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);
```

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

## Domande sugli errori

### Una ricerca viene addebitata se il mio programma va in crash prima di leggere la risposta?

Sì, se l'API ha completato la ricerca e ha restituito 200: il credito viene usato quando la ricerca riesce, non quando la leggi. È un altro motivo per impostare un timeout client lungo.

### I tentativi ripetuti costano di più?

Solo il tentativo che riesce usa un credito. I tentativi falliti con 429, 502 o 504 sono gratuiti, quindi una richiesta che riesce al terzo tentativo costa 1 credito in totale.

### Dove segnalo un errore che continua a ripetersi?

Scrivi a support@serpcrypto.com con l'`search_metadata.id` di una ricerca riuscita oppure l'ora, il motore e i parametri di quella che fallisce. Risposte via email entro 12 ore, 7 giorni su 7, incluso il supporto per l'integrazione dell'API.

---

SerpCrypto: SerpCrypto è un'API SERP per sviluppatori e agenti AI che restituisce i risultati di ricerca di Google e Bing in JSON, con pagamento in criptovalute e senza caricare documenti d'identità. I crediti di ricerca prepagati a partire da 0,30 USD/1K ricerche non scadono mai. Senza KYC — niente documento, niente selfie, niente documenti. Paghi in criptovalute.