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

> SerpCrypto SERP API 오류 코드: 400, 401, 402, 429, 502, 504, 각각의 원인, 해결 또는 재시도 방법, 그리고 어떤 오류도 크레딧을 사용하지 않는 이유.

- URL: https://serpcrypto.com/ko/docs/errors/
- 마지막 업데이트: 2026-10-22
- 발행자: SerpCrypto (https://serpcrypto.com)

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

**빠른 답변 — 어떤 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 상태 코드는 위 표와 일치합니다.

*402 응답의 본문*

```json
{
  "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](https://serpcrypto.com/ko/docs/search/)과(와) 비교해 보세요. 아무것도 과금되지 않으니 바로 고쳐서 다시 보내면 됩니다.

## 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](https://serpcrypto.com/ko/docs/python/) 및 [Node.js](https://serpcrypto.com/ko/docs/node/) 페이지에는 이 한도를 넘지 않는 풀이 나와 있습니다.

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

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

*Python: 지수 백오프로 429, 502, 504 재시도*

```python
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로 같은 로직 구현*

```javascript
// 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` 또는 실패한 검색의 시간, 엔진, 파라미터와 함께 support@serpcrypto.com로 보내주세요. 이메일 답변은 연중무휴, 주 7일 12시간 이내에 드리며, API 연동 지원도 포함됩니다.

---

SerpCrypto: SerpCrypto는 개발자와 AI 에이전트를 위한 SERP API로, Google 및 Bing 검색 결과를 JSON으로 반환하며 신분증 업로드 없이 암호화폐로 결제합니다. 선불 검색 크레딧 US$0.30/1K 검색는 만료되지 않습니다. KYC 없이 — 신분증도, 셀피도, 서류도 없습니다. 암호화폐 결제.