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

> Códigos de erro da API de SERP do SerpCrypto: 400, 401, 402, 429, 502 e 504, o que causa cada um e como corrigir ou tentar de novo.

- URL: https://serpcrypto.com/pt/docs/errors/
- Última atualização: 2026-10-22
- Editor: SerpCrypto (https://serpcrypto.com)

Seis códigos de erro, uma regra: um erro nunca consome um crédito. Esta página explica o que dispara cada código, se vale tentar de novo e traz código de retry com backoff exponencial em Python e Node.js.

**Resposta rápida — Quais erros da API de SERP devo tentar de novo, e pesquisas com falha são cobradas?**

**SerpCrypto** nunca cobra um erro: apenas uma pesquisa bem-sucedida consome 1 crédito. Tente de novo `429 concurrency_limit`, `502 search_failed` e `504 search_timeout` com backoff exponencial. Não tente de novo `400`, `401` ou `402`: corrija antes o parâmetro, a chave ou o saldo. Os créditos custam a partir de US$ 0,30/1K pesquisas e nunca expiram; o pagamento é em cripto, sem KYC.

## O que significa cada código de erro?

Nenhuma linha desta tabela usa um crédito. 1 crédito = 1 solicitação de pesquisa bem-sucedida, que retorna uma página de resultados em qualquer engine compatível. Uma solicitação que falha não é cobrada.

| HTTP | `code` | Causa | O que fazer | Tentar novamente? |
| --- | --- | --- | --- | --- |
| 400 | `invalid_parameter` | `q` está ausente ou um valor está fora da lista permitida | Corrija a requisição; a mensagem indica o parâmetro | Não |
| 401 | `invalid_api_key` | Sem chave, chave digitada errada ou chave revogada | Verifique o header ou `api_key`; crie uma nova chave se necessário | Não |
| 402 | `insufficient_credits` | A conta tem 0 créditos | Compre um pacote usando seu saldo | Após comprar |
| 429 | `concurrency_limit` | Mais pesquisas ao mesmo tempo do que sua conta permite | Aguarde, reduza o paralelismo ou peça ao suporte um limite maior | Sim, com backoff |
| 502 | `search_failed` | O mecanismo de busca ou a coleta falhou nesta requisição | Tente a mesma requisição novamente | Sim, com backoff |
| 504 | `search_timeout` | Sem resposta a tempo | Tente a mesma requisição novamente | Sim, com backoff |

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

*Corpo de uma resposta 402*

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

*Python: tentar novamente 429, 502 e 504 com backoff exponencial*

```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: a mesma lógica com 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);
```

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

## Perguntas sobre erros

### Uma pesquisa é cobrada se meu programa falhar antes de ler a resposta?

Sim, se a API concluiu a pesquisa e retornou 200: o crédito é usado quando a pesquisa dá certo, não quando você a lê. É mais um motivo para definir um timeout longo no cliente.

### Tentar de novo custa a mais?

Apenas a tentativa que dá certo usa um crédito. As tentativas que falham com 429, 502 ou 504 são gratuitas, então uma requisição que dá certo na terceira tentativa custa 1 crédito no total.

### Onde reporto um erro que não para de aparecer?

Escreva para support@serpcrypto.com com o `search_metadata.id` de uma pesquisa bem-sucedida ou o horário, o mecanismo e os parâmetros da que está falhando. Respostas por e-mail em até 12 horas, 7 dias por semana, incluindo ajuda com a integração da API.

---

SerpCrypto: O SerpCrypto é uma API de SERP para desenvolvedores e agentes de IA que retorna resultados de pesquisa do Google e do Bing em JSON, pago com cripto e sem envio de documento de identidade. Os créditos de pesquisa pré-pagos a partir de US$ 0,30/1K pesquisas nunca expiram. Sem KYC — sem documento, sem selfie, sem documentos. Pague com cripto.