SERP API errors: รหัส สาเหตุ การแก้ไข และการ retry

การตอบกลับแบบ error มีหน้าตาอย่างไร?

ทุก error มี JSON body ขนาดเล็กเหมือนกัน พร้อม code ที่คงที่และ message ที่อ่านได้ด้วยมนุษย์ แยกเงื่อนไขตาม code ในโปรแกรมของคุณและบันทึก message สำหรับมนุษย์ สถานะ HTTP ตรงกับตารางด้านบน

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

ทำไมฉันจึงได้ 400 invalid_parameter?

ค่าที่จำเป็นหายไป หรือค่าหนึ่งอยู่นอกเหนือรายการที่ API ยอมรับ สาเหตุที่พบบ่อยคือ q ว่าง, ชื่อ engine ที่พิมพ์ผิด เช่น google-news แทน google_news, page มากกว่า 10, หรือ device ที่ไม่ใช่ desktop หรือ mobile

message ระบุชื่อพารามิเตอร์ที่ผิดพลาด เปรียบเทียบคำขอของคุณกับ API reference; ไม่มีการเรียกเก็บเงิน ดังนั้นคุณสามารถแก้ไขและส่งใหม่ได้ทันที

ทำไมฉันจึงได้ 401 invalid_api_key?

key ไม่ถึง API หรือไม่ถูกต้อง ตรวจสอบว่า header เป็น Authorization: Bearer YOUR_KEY ตรง ๆ โดยมีช่องว่างหลัง Bearer ตรวจสอบด้วยว่า environment variable ของคุณถูกตั้งค่าใน shell หรือ service ที่รันโค้ด ไม่ใช่แค่ใน terminal ของคุณ key ที่ถูกเพิกถอนจะล้มเหลวต่อไป: สร้าง key ใหม่ใน dashboard

ฉันควรทำอย่างไรกับ 402 insufficient_credits?

ซื้อแพ็กเครดิตจากยอดคงเหลือของคุณ แล้วส่งใหม่ หากยอดคงเหลือต่ำเกินไป เติมด้วยคริปโตก่อน; ยอดเติมขั้นต่ำคือ US$25 อ่าน credits_remaining จาก GET https://serpcrypto.com/api/v1/credits ก่อนทำงานขนาดใหญ่เพื่อหลีกเลี่ยงการหยุดกลางทาง: การเรียกนั้นฟรี

ฉันจะจัดการ 429 concurrency_limit อย่างไร?

ชะลอความเร็วแทนที่จะหยุด ขีดจำกัดนับการค้นหาที่รันพร้อมกัน ไม่ใช่การค้นหาต่อวัน แต่ละบัญชีสามารถรันการค้นหาได้ตามจำนวนที่กำหนดในเวลาเดียวกัน; ขีดจำกัดแสดงอยู่ในแดชบอร์ดของคุณและเพิ่มได้เมื่อร้องขอ อ่าน concurrency_limit จาก endpoint เครดิตและกำหนดขนาด worker pool ของคุณให้สอดคล้อง; หน้า Python และ Node.js แสดง pool ที่ไม่เกินขีดจำกัด

502 และ 504 ถูกส่งกลับเมื่อใด?

502 search_failed หมายถึงการค้นหาไม่สามารถเสร็จสมบูรณ์สำหรับคำขอนี้; 504 search_timeout หมายถึงไม่เสร็จสมบูรณ์ในเวลาที่กำหนด ทั้งคู่ฟรีและทั้งคู่ควรลองใหม่ รอนานขึ้นเล็กน้อยก่อนแต่ละครั้งใหม่ ดังที่โค้ดด้านล่างทำ และเลิกหลังห้าครั้งเพื่อไม่ให้งานที่ค้างวนซ้ำตลอดไป

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 ของฉันควรสั้นหรือยาว?

ยาวพอให้การค้นหาเสร็จสมบูรณ์: การค้นหารันแบบ live ดังนั้นตั้ง client timeout เป็น 60 ถึง 90 วินาที แทนที่จะเป็นไม่กี่วินาที client ที่เลิกเร็วเกินไปจะส่งคำขอที่สองขณะที่คำขอแรกยังรันอยู่ ซึ่งเปลืองช่อง concurrency และหากทั้งคู่สำเร็จก็เสียสองเครดิต