# SERP APIのエラー: コード、原因、修正、リトライ

> SerpCrypto SERP APIのエラーコード: 400、401、402、429、502、504。それぞれの原因、修正またはリトライの方法、そしてエラーがクレジットを消費しない理由。

- URL: https://serpcrypto.com/ja/docs/errors/
- 最終更新: 2026-10-22
- 発行者: SerpCrypto (https://serpcrypto.com)

6つのエラーコード、1つのルール: エラーはクレジットを消費しません。このページでは各コードの発生条件、リトライすべきかどうか、そしてPythonとNode.jsでの指数バックオフを用いたリトライコードを説明します。

**簡潔な回答 — どのSERP APIエラーをリトライすべきで、失敗した検索は課金されますか？**

**SerpCrypto**はエラーに対して一切課金しません。成功した検索のみが1クレジットを消費します。`429 concurrency_limit`、`502 search_failed`、`504 search_timeout`は指数バックオフでリトライしてください。`400`、`401`、`402`はリトライしないでください。まずパラメータ、キー、残高を修正してください。クレジットは$0.30/1K検索からで、有効期限はありません。支払いは暗号資産で、KYC不要です。

## 各エラーコードの意味は何ですか？

この表のどの行もクレジットを消費しません。1クレジット = 1回の成功した検索リクエストで、対応するすべてのエンジンで結果の1ページを返します。失敗したリクエストは課金されません。

| HTTP | `code` | 原因 | 対処方法 | リトライ？ |
| --- | --- | --- | --- | --- |
| 400 | `invalid_parameter` | `q` が欠落しているか、許可リストにない値です | リクエストを修正してください。メッセージにパラメータ名が記載されています | いいえ |
| 401 | `invalid_api_key` | キーがない、キーの入力ミス、または失効したキーです | ヘッダーまたは `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` が問題のあるパラメータ名を示します。リクエストを [API reference](https://serpcrypto.com/ja/docs/search/) と照合してください。課金されないので、すぐに修正して再送できます。

## なぜ 401 invalid_api_key が返るのですか？

キーが API に届いていないか、有効ではありません。ヘッダーが正確に `Authorization: Bearer YOUR_KEY` であること、`Bearer` の後にスペースがあることを確認してください。また、環境変数がターミナルだけでなく、コードを実行する shell やサービスで設定されていることも確認してください。失効したキーは失敗し続けます。ダッシュボードで新しいキーを作成してください。

## 402 insufficient_credits にはどう対応すべきですか？

残高からクレジットパックを購入してから再送してください。残高が低すぎる場合は、先に暗号資産でチャージしてください。最低チャージ額は $25 です。大きなジョブの前に `GET https://serpcrypto.com/api/v1/credits` から `credits_remaining` を読み取って、途中で止まらないようにしてください。その呼び出しは無料です。

## 429 concurrency_limit はどう処理すればよいですか？

停止せずに速度を落としてください。この上限は1日の検索数ではなく、同時に実行中の検索数をカウントします。各アカウントは同時に一定数の検索を実行できます。上限はダッシュボードに表示され、リクエストに応じて引き上げられます。credits endpoint から `concurrency_limit` を読み取り、ワーカープールのサイズをそれに合わせてください。[Python](https://serpcrypto.com/ja/docs/python/) と [Node.js](https://serpcrypto.com/ja/docs/node/) のページには、上限を超えないプールの例が示されています。

## 502 と 504 はいつ返されますか？

`502 search_failed` はこのリクエストの検索を完了できなかったことを意味し、`504 search_timeout` は時間内に完了しなかったことを意味します。どちらも無料で、どちらもリトライする価値があります。以下のコードのように、新しい試行の前に少しずつ長く待機し、5回試行したら諦めてください。そうしないと、詰まったジョブが永遠にループします。

*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 秒に設定してください。早すぎるタイムアウトのクライアントは、最初のリクエストがまだ実行中なのに2つ目のリクエストを送信するため、並列処理スロットを無駄にし、両方が成功するとクレジットを2つ消費します。

## エラーの質問

### プログラムが応答を読む前にクラッシュした場合、検索は課金されますか？

はい、APIが検索を完了して200を返した場合は課金されます。クレジットは検索が成功した時点で消費され、あなたが応答を読む時点ではありません。これはクライアントのタイムアウトを長めに設定すべきもう一つの理由です。

### リトライには追加料金がかかりますか？

成功した試行だけがクレジットを消費します。429、502、504 で失敗した試行は無料なので、3回目で成功したリクエストの合計コストは1クレジットです。

### 繰り返し発生するエラーはどこに報告すればいいですか？

support@serpcrypto.com まで、成功した検索の `search_metadata.id`、または失敗した検索の時刻・エンジン・パラメータを添えてご連絡ください。メール返信は年中無休（7日間）12時間以内に対応し、API連携のサポートも含みます。

---

SerpCrypto: SerpCryptoは、開発者とAIエージェント向けのSERP APIで、GoogleとBingの検索結果をJSONで返し、身分証明書のアップロードなしで暗号資産で支払えます。前払いの検索クレジットは$0.30/1K検索から購入でき、有効期限はありません。KYC不要 — 身分証明書もセルフィーも書類も不要。暗号資産で支払い。