Erros da API de SERP: códigos, causas, correções e retries

Como é uma resposta de erro?

Todo erro tem o mesmo corpo JSON enxuto, com um code estável e uma message legível para humanos. Ramifique pelo code no seu programa e registre o message para as pessoas. O status HTTP corresponde à tabela acima.

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

Por que recebo 400 invalid_parameter?

Um valor obrigatório está ausente ou um valor está fora da lista que a API aceita. As causas mais comuns são um q vazio, um nome de mecanismo de busca com erro de digitação, como google-news em vez de google_news, um page acima de 10 ou um device diferente de desktop ou mobile.

O message indica o parâmetro com problema. Compare sua requisição com a referência da API; nada é cobrado, então você pode corrigir e reenviar na hora.

Por que recebo 401 invalid_api_key?

A chave não chegou à API ou não é válida. Verifique se o header é exatamente Authorization: Bearer YOUR_KEY, com um espaço depois de Bearer. Verifique também se sua variável de ambiente está definida no shell ou no serviço que executa o código, e não apenas no seu terminal. Uma chave revogada continua falhando: crie uma nova no dashboard.

O que devo fazer sobre 402 insufficient_credits?

Compre um pacote de créditos usando seu saldo e reenvie. Se o saldo estiver muito baixo, faça uma recarga com cripto primeiro; a recarga mínima é US$ 25. Leia credits_remaining em GET https://serpcrypto.com/api/v1/credits antes de um trabalho grande para evitar parar no meio: essa chamada é gratuita.

Como lidar com 429 concurrency_limit?

Reduza o ritmo em vez de parar. O limite conta pesquisas em execução ao mesmo tempo, não pesquisas por dia. Cada conta pode executar um número definido de pesquisas ao mesmo tempo; o limite é exibido no seu painel e aumentado sob solicitação. Leia concurrency_limit no endpoint de créditos e dimensione seu pool de workers conforme esse valor; as páginas Python e Node.js mostram um pool que nunca o excede.

Quando 502 e 504 são retornados?

502 search_failed significa que a pesquisa não pôde ser concluída nesta requisição; 504 search_timeout significa que ela não foi concluída a tempo. Ambos são gratuitos e ambos valem uma nova tentativa. Espere um pouco mais antes de cada nova tentativa, como faz o código abaixo, e desista após cinco tentativas para que um trabalho travado não fique em loop para sempre.

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

Meu timeout HTTP deve ser curto ou longo?

Longo o suficiente para uma pesquisa terminar: a pesquisa é executada ao vivo, então configure o timeout do seu cliente para 60 a 90 segundos em vez de alguns segundos. Um cliente que desiste cedo demais envia uma segunda requisição enquanto a primeira ainda está em execução, o que desperdiça um slot de concorrência e, se ambas forem bem-sucedidas, dois créditos.