Error SERP API: kode, penyebab, perbaikan dan retry

Seperti apa bentuk jawaban error?

Setiap error punya body JSON kecil yang sama dengan code yang stabil dan message yang mudah dibaca manusia. Percabangkan program Anda berdasarkan code dan catat message untuk dibaca manusia. Status HTTP-nya sesuai tabel di atas.

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

Mengapa saya mendapat 400 invalid_parameter?

Ada nilai wajib yang tidak ada atau ada nilai di luar daftar yang diterima API. Penyebab umumnya adalah q kosong, nama engine yang salah ketik seperti google-news alih-alih google_news, page di atas 10, atau device selain desktop atau mobile.

message menyebutkan parameter yang bermasalah. Bandingkan request Anda dengan referensi API; tidak ada yang dikenakan biaya, jadi Anda bisa memperbaiki dan mengirim ulang saat itu juga.

Mengapa saya mendapat 401 invalid_api_key?

API key tidak sampai ke API, atau tidak valid. Periksa bahwa header-nya persis Authorization: Bearer YOUR_KEY, dengan spasi setelah Bearer. Periksa juga bahwa environment variable Anda sudah diatur di shell atau service yang menjalankan kode, bukan hanya di terminal Anda. API key yang dicabut akan terus gagal: buat API key baru di dashboard.

Apa yang harus saya lakukan dengan 402 insufficient_credits?

Beli paket kredit dari saldo Anda, lalu kirim ulang. Jika saldo terlalu rendah, top up dengan kripto dulu; top up minimum US$25. Baca credits_remaining dari GET https://serpcrypto.com/api/v1/credits sebelum job besar agar tidak berhenti di tengah jalan: panggilan itu gratis.

Bagaimana menangani 429 concurrency_limit?

Perlambat, jangan berhenti. Limit menghitung pencarian yang berjalan bersamaan, bukan pencarian per hari. Setiap akun dapat menjalankan sejumlah pencarian secara bersamaan; batasnya ditampilkan di dashboard Anda dan dinaikkan atas permintaan. Baca concurrency_limit dari endpoint kredit dan sesuaikan ukuran worker pool Anda dengannya; halaman Python dan Node.js menunjukkan pool yang tidak pernah melewatinya.

Kapan 502 dan 504 dikembalikan?

502 search_failed berarti pencarian tidak bisa diselesaikan untuk request ini; 504 search_timeout berarti pencarian tidak selesai tepat waktu. Keduanya gratis dan keduanya layak dicoba lagi. Tunggu lebih lama sebelum setiap percobaan baru, seperti yang dilakukan kode di bawah, dan menyerah setelah lima percobaan agar job yang macet tidak berulang selamanya.

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

Apakah timeout HTTP saya harus pendek atau panjang?

Cukup panjang agar pencarian selesai: pencarian berjalan live, jadi atur timeout client Anda ke 60 sampai 90 detik, bukan beberapa detik. Client yang menyerah terlalu cepat mengirim request kedua saat request pertama masih berjalan, yang membuang satu slot konkurensi dan, jika keduanya berhasil, dua kredit.