SERP API errors: codes, causes, fixes and retries

What does an error answer look like?

Every error has the same small JSON body with a stable code and a human-readable message. Branch on code in your program and log message for people. The HTTP status matches the table above.

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

Why do I get 400 invalid_parameter?

A required value is missing or one value is outside the list the API accepts. The usual causes are an empty q, an engine name with a typo such as google-news instead of google_news, a page above 10, or a device other than desktop or mobile.

The message names the parameter at fault. Compare your request with the API reference; nothing is charged, so you can correct and resend at once.

Why do I get 401 invalid_api_key?

The key did not reach the API, or it is not valid. Check that the header is exactly Authorization: Bearer YOUR_KEY, with a space after Bearer. Check also that your environment variable is set in the shell or service that runs the code, not only in your terminal. A revoked key keeps failing: create a new one in the dashboard.

What should I do about 402 insufficient_credits?

Buy a credit pack from your balance, then resend. If the balance is too low, top up in crypto first; the minimum top-up is $25. Read credits_remaining from GET https://serpcrypto.com/api/v1/credits before a large job to avoid stopping halfway: that call is free.

How do I handle 429 concurrency_limit?

Slow down rather than stop. The limit counts searches running at the same time, not searches per day. Each account can run a set number of searches at the same time; the limit is shown in your dashboard and raised on request. Read concurrency_limit from the credits endpoint and size your worker pool to it; the Python and Node.js pages show a pool that never exceeds it.

When are 502 and 504 returned?

502 search_failed means the search could not be completed for this request; 504 search_timeout means it did not complete in time. Both are free and both are worth retrying. Wait a little longer before each new attempt, as the code below does, and give up after five attempts so a stuck job does not loop for ever.

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

Should my HTTP timeout be short or long?

Long enough for a search to finish: a search runs live, so set your client timeout to 60 to 90 seconds rather than a few seconds. A client that gives up too early sends a second request while the first is still running, which wastes a concurrency slot and, if both succeed, two credits.