SERP API hataları: kodlar, nedenler, düzeltmeler ve yeniden denemeler

Hata yanıtı nasıl görünür?

Her hatanın, sabit bir code ve insan tarafından okunabilir bir message içeren aynı küçük JSON gövdesi vardır. Programınızda code üzerine dallanın ve insanlar için message kaydını tutun. HTTP durum kodu yukarıdaki tabloyla eşleşir.

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

Neden 400 invalid_parameter alıyorum?

Zorunlu bir değer eksik veya bir değer API'nin kabul ettiği listenin dışında. Olağan nedenler şunlardır: boş bir q, google_news yerine google-news gibi yazım hatası içeren bir motor adı, 10'un üzerinde bir page veya desktop ya da mobile dışında bir device.

message sorunlu parametreyi belirtir. İsteğinizi API reference ile karşılaştırın; hiçbir ücret alınmaz, bu yüzden hemen düzeltip yeniden gönderebilirsiniz.

Neden 401 invalid_api_key alıyorum?

Anahtar API'ye ulaşmadı veya geçerli değil. Header'ın tam olarak Authorization: Bearer YOUR_KEY olduğundan ve Bearer sonrasında bir boşluk bulunduğundan emin olun. Ayrıca ortam değişkeninizin yalnızca terminalinizde değil, kodu çalıştıran shell'de veya serviste tanımlı olduğunu kontrol edin. İptal edilmiş bir anahtar hata vermeye devam eder: dashboard'da yeni bir anahtar oluşturun.

402 insufficient_credits için ne yapmalıyım?

Bakiyenizden bir kredi paketi satın alın, ardından yeniden gönderin. Bakiye çok düşükse önce kripto ile bakiye yükleyin; minimum yükleme tutarı $25. Büyük bir işten önce yarıda kalmamak için GET https://serpcrypto.com/api/v1/credits üzerinden credits_remaining değerini okuyun: bu çağrı ücretsizdir.

429 concurrency_limit ile nasıl başa çıkarım?

Durmak yerine yavaşlayın. Limit, günde yapılan aramaları değil, aynı anda çalışan aramaları sayar. Her hesap aynı anda belirli sayıda arama çalıştırabilir; limit dashboard'ınızda gösterilir ve talep üzerine yükseltilir. Krediler endpoint'inden concurrency_limit değerini okuyun ve worker havuzunuzu buna göre boyutlandırın; Python ve Node.js sayfaları bu limiti hiç aşmayan bir havuz gösterir.

502 ve 504 ne zaman döner?

502 search_failed, aramanın bu istek için tamamlanamadığı anlamına gelir; 504 search_timeout ise zamanında tamamlanamadığı anlamına gelir. Her ikisi de ücretsizdir ve her ikisi de yeniden denenmeye değer. Aşağıdaki kodun yaptığı gibi her yeni denemeden önce biraz daha uzun bekleyin ve takılı bir işin sonsuza kadar döngüde kalmaması için beş denemeden sonra vazgeçin.

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

HTTP timeout sürem kısa mı yoksa uzun mu olmalı?

Bir aramanın tamamlanmasına yetecek kadar uzun: arama canlı çalışır, bu yüzden istemci timeout sürenizi birkaç saniye yerine 60 ila 90 saniye olarak ayarlayın. Çok erken vazgeçen bir istemci, ilk istek hâlâ çalışırken ikinci bir istek gönderir; bu bir eşzamanlılık slotunu boşa harcar ve ikisi de başarılı olursa iki kredi harcar.