Lỗi SERP API: mã, nguyên nhân, cách sửa và retry

Một câu trả lời lỗi trông như thế nào?

Mọi lỗi đều có cùng một JSON body nhỏ gọn với code ổn định và message dễ đọc cho người. Rẽ nhánh theo code trong chương trình của bạn và ghi log message cho người đọc. HTTP status khớp với bảng ở trên.

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

Vì sao tôi nhận 400 invalid_parameter?

Thiếu một giá trị bắt buộc hoặc có giá trị nằm ngoài danh sách API chấp nhận. Nguyên nhân thường gặp là q rỗng, tên engine gõ sai như google-news thay vì google_news, page lớn hơn 10, hoặc device khác desktop và mobile.

message chỉ ra tham số bị lỗi. Đối chiếu truy vấn của bạn với tài liệu API; không bị tính phí nên bạn có thể sửa và gửi lại ngay.

Vì sao tôi nhận 401 invalid_api_key?

Khóa không đến được API, hoặc khóa không hợp lệ. Kiểm tra header đúng chính xác là Authorization: Bearer YOUR_KEY, có dấu cách sau Bearer. Đồng thời kiểm tra biến môi trường đã được đặt trong shell hoặc service chạy code, không chỉ trong terminal của bạn. Khóa đã bị thu hồi sẽ tiếp tục lỗi: tạo khóa mới trong dashboard.

Tôi nên làm gì với 402 insufficient_credits?

Mua một pack credit bằng số dư của bạn rồi gửi lại. Nếu số dư quá thấp, nạp thêm bằng crypto trước; mức nạp tối thiểu là 25 US$. Đọc credits_remaining từ GET https://serpcrypto.com/api/v1/credits trước khi chạy job lớn để tránh dừng giữa chừng: lệnh gọi đó miễn phí.

Làm sao xử lý 429 concurrency_limit?

Hãy chậm lại thay vì dừng. Giới hạn này đếm số truy vấn chạy cùng lúc, không phải số truy vấn mỗi ngày. Mỗi tài khoản có thể chạy một số lượng truy vấn tìm kiếm cùng lúc; giới hạn được hiển thị trong dashboard và có thể tăng theo yêu cầu. Đọc concurrency_limit từ endpoint credits và chỉnh kích thước pool worker theo đó; các trang Python và Node.js có ví dụ pool không bao giờ vượt giới hạn.

Khi nào trả về 502 và 504?

502 search_failed nghĩa là truy vấn không thể hoàn tất với yêu cầu này; 504 search_timeout nghĩa là truy vấn không hoàn tất kịp thời. Cả hai đều miễn phí và đều đáng thử lại. Chờ lâu hơn một chút trước mỗi lần thử mới, như code bên dưới làm, và bỏ cuộc sau năm lần thử để job bị kẹt không lặp mãi.

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 của tôi nên ngắn hay dài?

Đủ dài để một truy vấn hoàn tất: truy vấn chạy trực tiếp, nên đặt timeout phía client là 60 đến 90 giây thay vì vài giây. Client bỏ cuộc quá sớm sẽ gửi truy vấn thứ hai khi truy vấn đầu vẫn đang chạy, vừa lãng phí một slot chạy song song, vừa tốn hai credit nếu cả hai đều thành công.