KYC 없이 — 신분증, 셀피, 서류 없음. 암호화폐로 결제: BTC, USDT, USDC, ETH, SOL, LTC
언어: 한국어
API 키 발급

문서 · 오류 · API v1

SERP API 오류: 코드, 원인, 해결 및 재시도

여섯 가지 오류 코드, 하나의 규칙: 오류는 절대 크레딧을 사용하지 않습니다. 이 페이지는 각 코드를 유발하는 원인, 재시도 여부, 그리고 Python과 Node.js로 지수 백오프를 적용한 재시도 코드를 알려줍니다.

마지막 업데이트: · 4 분 소요

빠른 답변

어떤 SERP API 오류를 재시도해야 하며, 실패한 검색에 요금이 부과되나요?

SerpCrypto은 오류에 절대 요금을 부과하지 않습니다. 성공한 검색만 1 크레딧을 사용합니다. 429 concurrency_limit, 502 search_failed, 504 search_timeout는 지수 백오프로 재시도하세요. 400, 401, 402은 재시도하지 마세요. 먼저 매개변수, 키 또는 잔액을 수정해야 합니다. 크레딧은 US$0.30/1K 검색부터이며 만료되지 않습니다. 결제는 암호화폐로, KYC 없이 이루어집니다.

각 오류 코드는 무엇을 의미하나요?

이 표의 어떤 행도 크레딧을 사용하지 않습니다. 1 크레딧 = 성공한 검색 요청 1건이며, 지원되는 모든 엔진에서 결과 한 페이지를 반환합니다. 실패한 요청은 과금되지 않습니다.

HTTPcode원인무엇을 해야 하나요재시도할까요?
400invalid_parameterq이(가) 없거나 허용 목록을 벗어난 값입니다요청을 수정하세요. 메시지에 해당 parameter 이름이 표시됩니다아니요
401invalid_api_key키가 없거나, 키 오타이거나, 폐기된 키입니다header 또는 api_key을(를) 확인하고, 필요하면 새 키를 만드세요아니요
402insufficient_credits계정 크레딧이 0입니다잔액에서 팩을 구매하세요구매 후
429concurrency_limit계정이 허용하는 동시 검색 수를 초과했습니다기다리거나, 병렬 실행 수를 낮추거나, 지원팀에 한도 상향을 요청하세요예, 백오프와 함께
502search_failed이 요청에서 엔진 또는 컬렉션이 실패했습니다같은 요청을 재시도하세요예, 백오프와 함께
504search_timeout제시간에 응답이 없습니다같은 요청을 재시도하세요예, 백오프와 함께

에러 응답은 어떻게 생겼나요?

모든 에러는 안정적인 code과(와) 사람이 읽을 수 있는 message을(를) 담은 동일한 작은 JSON 본문을 가집니다. 프로그램에서는 code로 분기하고, 사람을 위해 message을(를) 기록하세요. HTTP 상태 코드는 위 표와 일치합니다.

402 응답의 본문
{
  "error": {
    "code": "insufficient_credits",
    "message": "Your account has no search credits left."
  }
}

400 invalid_parameter는 왜 발생하나요?

필수 값이 빠졌거나 어떤 값이 API가 허용하는 목록을 벗어났습니다. 흔한 원인은 빈 q, google_news 대신 google-news처럼 엔진 이름에 오타가 있는 경우, 10을 초과한 page, desktop 또는 mobile이(가) 아닌 device입니다.

message이(가) 문제가 된 parameter를 알려줍니다. 요청을 API reference과(와) 비교해 보세요. 아무것도 과금되지 않으니 바로 고쳐서 다시 보내면 됩니다.

401 invalid_api_key는 왜 발생하나요?

키가 API에 도달하지 않았거나 유효하지 않습니다. header가 정확히 Authorization: Bearer YOUR_KEY이고 Bearer 뒤에 공백이 있는지 확인하세요. 환경 변수가 터미널에만이 아니라 코드를 실행하는 셸이나 서비스에 설정되어 있는지도 확인하세요. 폐기된 키는 계속 실패하니 대시보드에서 새 키를 만드세요.

402 insufficient_credits는 어떻게 해야 하나요?

잔액에서 크레딧 팩을 구매한 뒤 다시 보내세요. 잔액이 너무 적으면 먼저 암호화폐로 충전하세요. 최소 충전 금액은 US$25입니다. 큰 작업 전에 GET https://serpcrypto.com/api/v1/credits에서 credits_remaining을(를) 읽어 중간에 멈추는 일을 피하세요. 이 호출은 무료입니다.

429 concurrency_limit는 어떻게 처리하나요?

멈추기보다 속도를 줄이세요. 이 한도는 하루 검색 수가 아니라 동시에 실행되는 검색 수를 셉니다. 각 계정은 동시에 정해진 수의 검색을 실행할 수 있으며, 한도는 대시보드에 표시되고 요청 시 상향됩니다. credits endpoint에서 concurrency_limit을(를) 읽고 그에 맞춰 워커 풀 크기를 정하세요. Python 및 Node.js 페이지에는 이 한도를 넘지 않는 풀이 나와 있습니다.

502와 504는 언제 반환되나요?

502 search_failed은(는) 이 요청에 대해 검색을 완료할 수 없었다는 뜻이고, 504 search_timeout은(는) 제시간에 완료되지 않았다는 뜻입니다. 둘 다 무료이고 둘 다 재시도할 가치가 있습니다. 아래 코드처럼 새 시도 전에 조금씩 더 기다리고, 멈춘 작업이 영원히 반복되지 않도록 다섯 번 시도 후 포기하세요.

Python: 지수 백오프로 429, 502, 504 재시도
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"])
Node.js: fetch로 같은 로직 구현
// 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 타임아웃은 짧게 잡아야 하나요, 길게 잡아야 하나요?

검색이 끝날 수 있을 만큼 길게 잡으세요. 검색은 실시간으로 실행되므로 클라이언트 타임아웃을 몇 초가 아니라 60~90초로 설정하세요. 너무 일찍 포기하는 클라이언트는 첫 요청이 아직 실행 중인데 두 번째 요청을 보내 동시 실행 슬롯을 낭비하고, 둘 다 성공하면 크레딧을 두 개 사용합니다.

에러 관련 질문

프로그램이 답변을 읽기 전에 크래시되면 검색 요금이 청구되나요?

예. API가 검색을 완료하고 200을 반환했다면 청구됩니다. 크레딧은 검색이 성공할 때 사용되며, 답변을 읽을 때 사용되는 것이 아닙니다. 클라이언트 타임아웃을 길게 설정해야 하는 또 다른 이유입니다.

재시도하면 추가 요금이 발생하나요?

성공한 시도만 크레딧을 사용합니다. 429, 502, 504로 실패한 시도는 무료이므로, 세 번째 시도에서 성공한 요청은 총 1 크레딧이 듭니다.

계속 반복되는 오류는 어디에 신고하나요?

성공한 검색의 search_metadata.id 또는 실패한 검색의 시간, 엔진, 파라미터와 함께 [email protected]로 보내주세요. 이메일 답변은 연중무휴, 주 7일 12시간 이내에 드리며, API 연동 지원도 포함됩니다.

US$0.30/1K 검색부터 · KYC 없이

API 키 발급