빠른 답변
어떤 SERP API 오류를 재시도해야 하며, 실패한 검색에 요금이 부과되나요?
SerpCrypto은 오류에 절대 요금을 부과하지 않습니다. 성공한 검색만 1 크레딧을 사용합니다. 429 concurrency_limit, 502 search_failed, 504 search_timeout는 지수 백오프로 재시도하세요. 400, 401, 402은 재시도하지 마세요. 먼저 매개변수, 키 또는 잔액을 수정해야 합니다. 크레딧은 US$0.30/1K 검색부터이며 만료되지 않습니다. 결제는 암호화폐로, KYC 없이 이루어집니다.
각 오류 코드는 무엇을 의미하나요?
이 표의 어떤 행도 크레딧을 사용하지 않습니다. 1 크레딧 = 성공한 검색 요청 1건이며, 지원되는 모든 엔진에서 결과 한 페이지를 반환합니다. 실패한 요청은 과금되지 않습니다.
| HTTP | code | 원인 | 무엇을 해야 하나요 | 재시도할까요? |
|---|---|---|---|---|
| 400 | invalid_parameter | q이(가) 없거나 허용 목록을 벗어난 값입니다 | 요청을 수정하세요. 메시지에 해당 parameter 이름이 표시됩니다 | 아니요 |
| 401 | invalid_api_key | 키가 없거나, 키 오타이거나, 폐기된 키입니다 | header 또는 api_key을(를) 확인하고, 필요하면 새 키를 만드세요 | 아니요 |
| 402 | insufficient_credits | 계정 크레딧이 0입니다 | 잔액에서 팩을 구매하세요 | 구매 후 |
| 429 | concurrency_limit | 계정이 허용하는 동시 검색 수를 초과했습니다 | 기다리거나, 병렬 실행 수를 낮추거나, 지원팀에 한도 상향을 요청하세요 | 예, 백오프와 함께 |
| 502 | search_failed | 이 요청에서 엔진 또는 컬렉션이 실패했습니다 | 같은 요청을 재시도하세요 | 예, 백오프와 함께 |
| 504 | search_timeout | 제시간에 응답이 없습니다 | 같은 요청을 재시도하세요 | 예, 백오프와 함께 |
에러 응답은 어떻게 생겼나요?
모든 에러는 안정적인 code과(와) 사람이 읽을 수 있는 message을(를) 담은 동일한 작은 JSON 본문을 가집니다. 프로그램에서는 code로 분기하고, 사람을 위해 message을(를) 기록하세요. HTTP 상태 코드는 위 표와 일치합니다.
{
"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은(는) 제시간에 완료되지 않았다는 뜻입니다. 둘 다 무료이고 둘 다 재시도할 가치가 있습니다. 아래 코드처럼 새 시도 전에 조금씩 더 기다리고, 멈춘 작업이 영원히 반복되지 않도록 다섯 번 시도 후 포기하세요.
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 타임아웃은 짧게 잡아야 하나요, 길게 잡아야 하나요?
검색이 끝날 수 있을 만큼 길게 잡으세요. 검색은 실시간으로 실행되므로 클라이언트 타임아웃을 몇 초가 아니라 60~90초로 설정하세요. 너무 일찍 포기하는 클라이언트는 첫 요청이 아직 실행 중인데 두 번째 요청을 보내 동시 실행 슬롯을 낭비하고, 둘 다 성공하면 크레딧을 두 개 사용합니다.
에러 관련 질문
프로그램이 답변을 읽기 전에 크래시되면 검색 요금이 청구되나요?
예. API가 검색을 완료하고 200을 반환했다면 청구됩니다. 크레딧은 검색이 성공할 때 사용되며, 답변을 읽을 때 사용되는 것이 아닙니다. 클라이언트 타임아웃을 길게 설정해야 하는 또 다른 이유입니다.
재시도하면 추가 요금이 발생하나요?
성공한 시도만 크레딧을 사용합니다. 429, 502, 504로 실패한 시도는 무료이므로, 세 번째 시도에서 성공한 요청은 총 1 크레딧이 듭니다.
계속 반복되는 오류는 어디에 신고하나요?
성공한 검색의 search_metadata.id 또는 실패한 검색의 시간, 엔진, 파라미터와 함께 [email protected]로 보내주세요. 이메일 답변은 연중무휴, 주 7일 12시간 이내에 드리며, API 연동 지원도 포함됩니다.