Web・開発

PHPでAPIタイムアウト、レートリミット、リトライを処理する方法

How to Handle API Timeouts, Rate Limits, and Retries in PHP

接続タイムアウト、HTTPエラー処理、指数関数的バックオフ、Retry-Afterサポート、安全なリトライ戦略を備えた信頼性の高いPHP API統合を構築する方法を学びましょう。

PHPでAPIタイムアウト、レート制限、リトライを処理する方法

API統合は開発中は完璧に動作します。しかしある日、スケジュールタスクが途中で停止します。リモートサービスがHTTP 429を返し、接続がタイムアウトし、またはHTTP 503エラーが同期を中断させます。

すぐにリクエストを再試行したくなります。

しかし、戦略なしに再試行すると問題を悪化させる可能性があります。すでに苦戦しているAPIに過負荷をかけたり、レート制限を超えたり、誤って重複注文や重複支払いを作成したりする可能性があります。

信頼できるAPIクライアントには、成功するcurl_exec()呼び出し以上のものが必要です。

このチュートリアルでは、接続タイムアウト、HTTPエラー、レート制限、一時的な障害を処理する実用的なPHP HTTPクライアントを構築します。また、いつリトライが安全か、いつ安全でないか、本番環境で問題を診断する方法についても説明します。

例では、Composerやサードパーティの依存関係なしで、PHPの組み込みcURL拡張機能を使用します。

1. API障害の種類を理解する

すべての失敗したリクエストを同じように処理すべきではありません。

障害 典型的な原因 推奨される対応
接続タイムアウト サーバーに到達不能、または接続が遅い 慎重にリトライ
HTTP 400 無効なリクエストパラメータ リクエストを修正
HTTP 401 無効または期限切れの認証情報 認証を確認
HTTP 404 リソースが見つからない リソース識別子を確認
HTTP 429 APIレート制限超過 Retry-Afterを尊重
HTTP 500 内部サーバーエラー 選択的にリトライ
HTTP 503 サービス一時的利用不可 遅延を伴ってリトライ
無効なJSON 予期しないレスポンス形式 ログを記録し調査

ネットワークエラーもHTTPエラーとは異なります。

APIがHTTP 500を返す場合、HTTPリクエストは完了し、サーバーがエラーレスポンスを返しています。

cURLが接続失敗を報告する場合、アプリケーションはHTTPレスポンスを一切受信していない可能性があります。

この違いは、リトライすべきかどうかを判断する際に重要です。

2. 常に接続タイムアウトとリクエストタイムアウトを設定する

PHP cURLには、特に有用な2つの設定があります:

CURLOPT_CONNECTTIMEOUT => 5,
CURLOPT_TIMEOUT => 15,

CURLOPT_CONNECTTIMEOUTは接続フェーズを制限し、CURLOPT_TIMEOUTは全体の転送時間を制限します。両方ともPHPの公式cURLリファレンスで文書化されています。

適切な制限がないと、遅い外部サービスが予想以上に長くPHPワーカーを占有する可能性があります。

一般的なJSON APIの実用的な出発点としては、接続確立に5秒、完全なリクエストに15秒程度が考えられます。

これらは万能な値ではありません。ファイルアップロードや長時間実行されるレポート生成には、異なるタイムアウトポリシーが必要な場合があります。

最初のAPIリクエストを作成する

<?php
declare(strict_types=1);

$url = 'https://api.example.com/products';

$curl = curl_init($url);

curl_setopt_array($curl, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CONNECTTIMEOUT => 5,
    CURLOPT_TIMEOUT => 15,
    CURLOPT_FOLLOWLOCATION => false,
]);

$response = curl_exec($curl);
$statusCode = curl_getinfo(
    $curl,
    CURLINFO_HTTP_CODE
);

if ($response === false) {
    $error = curl_error($curl);

    curl_close($curl);

    throw new RuntimeException(
        'API request failed: ' . $error
    );
}

curl_close($curl);

echo 'HTTP status: ' . $statusCode;

これは有用な基盤を確立しますが、まだレート制限やリトライ可能な障害は処理していません。

3. HTTP 429とRetry-Afterを理解する

HTTP 429は、クライアントがAPIプロバイダーが定義する期間内に多くのリクエストを送信したことを意味します。

一部のAPIは、分単位、時間単位、APIキー単位、アカウント単位で制限を課します。

サーバーは以下のように応答することがあります:

HTTP/1.1 429 Too Many Requests
Retry-After: 60
Content-Type: application/json

Retry-Afterヘッダーは、クライアントが再試行する前にどのくらい待つべきかを伝えます。

このヘッダーには、秒数またはHTTP日付のいずれかを含めることができます。

例:

Retry-After: 120

または:

Retry-After: Wed, 25 Nov 2026 10:00:00 GMT

適切なクライアントは、繰り返しリクエストを送信するのではなく、この指示を尊重すべきです。

サーバーが再試行遅延を提供しない場合、アプリケーションにはフォールバック戦略が必要です。

4. 即座のリトライの代わりに指数バックオフを使用する

指数バックオフは、連続する障害の後に待機時間を増やします。

例:

リトライ 遅延の例
1 1秒
2 2秒
3 4秒
4 8秒

毎秒リトライする代わりに、アプリケーションは徐々に長く待機します。

ジッターと呼ばれる小さなランダムな変動を追加すると、多くのクライアントが同時にリトライするのを防止できます。

再利用可能な遅延関数はこちら:

<?php
declare(strict_types=1);

function getRetryDelayMs(int $attempt): int
{
    $baseDelay = 1000;
    $maximumDelay = 30000;

    $exponentialDelay = min(
        $maximumDelay,
        $baseDelay * (2 ** ($attempt - 1))
    );

    return random_int(
        0,
        (int)$exponentialDelay
    );
}

これはフルジッターを使用します:実際の遅延は、ゼロと指数的な上限の間でランダムに選択されます。

ランダムな遅延は同期されたリトライバーストを軽減しますが、明示的なサーバー提供のRetry-After指示に取って代わるものではありません。

Illustration of the article's main concept

5. 再利用可能なPHP APIクライアントを構築する

前の概念を動作する実装に組み合わせましょう。

このクライアントは:

  • 接続および全体のリクエストタイムアウトを設定する。
  • HTTPステータスとレスポンスボディを返す。
  • トランスポート障害を検出する。
  • 選択された一時的な障害をリトライする。
  • 存在する場合はRetry-Afterを尊重する。
  • 試行回数を制限する。
  • 非冪等操作を自動的にリトライしない。
<?php
declare(strict_types=1);

/**
 * Perform an HTTP GET request with bounded retries.
 *
 * Use only with trusted, configured API URLs.
 */
function apiGet(
    string $url,
    int $maxAttempts = 3
): array {
    if ($maxAttempts < 1) {
        throw new InvalidArgumentException(
            'maxAttempts must be at least 1.'
        );
    }

    for ($attempt = 1; $attempt <= $maxAttempts; $attempt++) {
        $headers = [];

        $curl = curl_init($url);

        if ($curl === false) {
            throw new RuntimeException(
                'Unable to initialize cURL.'
            );
        }

        curl_setopt_array($curl, [
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_CONNECTTIMEOUT => 5,
            CURLOPT_TIMEOUT => 15,
            CURLOPT_FOLLOWLOCATION => false,
            CURLOPT_HTTPGET => true,
            CURLOPT_HEADERFUNCTION => static function (
                $curl,
                string $headerLine
            ) use (&$headers): int {
                $length = strlen($headerLine);

                if (str_starts_with(
                    $headerLine,
                    'HTTP/'
                )) {
                    $headers = [];
                }

                $position = strpos(
                    $headerLine,
                    ':'
                );

                if ($position !== false) {
                    $name = strtolower(trim(
                        substr($headerLine, 0, $position)
                    ));

                    $value = trim(
                        substr($headerLine, $position + 1)
                    );

                    $headers[$name] = $value;
                }

                return $length;
            },
        ]);

        $body = curl_exec($curl);
        $curlError = curl_errno($curl);
        $statusCode = (int)curl_getinfo(
            $curl,
            CURLINFO_HTTP_CODE
        );

        curl_close($curl);

        $transportFailure = $body === false;

        $retryableStatus = in_array(
            $statusCode,
            [408, 429, 500, 502, 503, 504],
            true
        );

        if (!$transportFailure && !$retryableStatus) {
            return [
                'status' => $statusCode,
                'body' => $body,
                'headers' => $headers,
                'attempts' => $attempt,
            ];
        }

        if ($attempt === $maxAttempts) {
            throw new RuntimeException(
                'API request failed after '
                . $attempt
                . ' attempts. HTTP '
                . $statusCode
                . ', cURL error '
                . $curlError
            );
        }

        $delayMs = min(
            30000,
            1000 * (2 ** ($attempt - 1))
        );

        $retryAfter = $headers['retry-after'] ?? null;

        if ($retryAfter !== null) {
            if (ctype_digit($retryAfter)) {
                $delayMs = (int)$retryAfter * 1000;
            } else {
                $timestamp = strtotime($retryAfter);

                if ($timestamp !== false) {
                    $delayMs = max(
                        0,
                        $timestamp - time()
                    ) * 1000;
                }
            }
        } else {
            $delayMs = random_int(
                0,
                (int)$delayMs
            );
        }

        // Do not block this worker indefinitely.
        if ($delayMs > 30000) {
            throw new RuntimeException(
                'Retry deferred: waiting time exceeds '
                . 'the synchronous retry budget.'
            );
        }

        usleep((int)$delayMs * 1000);
    }

    throw new RuntimeException(
        'Unexpected retry state.'
    );
}

使用方法

<?php
declare(strict_types=1);

try {
    $result = apiGet(
        'https://api.example.com/products'
    );

    if ($result['status'] !== 200) {
        throw new RuntimeException(
            'Unexpected HTTP status: '
            . $result['status']
        );
    }

    $products = json_decode(
        $result['body'],
        true,
        512,
        JSON_THROW_ON_ERROR
    );

    echo 'API request completed after '
        . $result['attempts']
        . ' attempt(s).';

} catch (Throwable $exception) {
    error_log($exception->getMessage());
}

この実装は、信頼できるAPIエンドポイントに対するGETリクエストに意図的に限定されています。

POST、PUT、PATCH、DELETE操作は追加の安全装置を必要とするため、自動的にはリトライしません。

また、リトライ不可能なHTTPレスポンスは呼び出し元に返され、呼び出し元がどのように処理するかを決定する必要があります。

本番システムでは、さらにレスポンスタイプの検証、レスポンスサイズ制限の実施、リトライ可能なトランスポートエラーと永続的なTLSまたは設定障害の区別を行うべきです。

6. POSTリクエストのリトライが危険な理由

Eコマースアプリケーションがこのリクエストを送信することを想像してください:

POST /api/orders
Content-Type: application/json

{
  "product_id": 42,
  "quantity": 1
}

リモートAPIが注文を作成しましたが、アプリケーションがレスポンスを受信する前に接続が切断されました。

アプリケーションはタイムアウトを検知します。

注文は失敗したでしょうか?

必ずしもそうではありません。注文はすでに存在している可能性があります。

アプリケーションが即座にリトライすると、2つ目の注文が作成される可能性があります。

これが「タイムアウトはサーバー側で操作が失敗したことを証明しない」理由です。

サポートされている場合は冪等性キーを使用する

一部のAPIは冪等性キーをサポートしています。

例:

Idempotency-Key: order-8f7a2c

APIが文書化された冪等性メカニズムを提供している場合、同じ論理操作のリトライに同じキーを再利用すると、重複処理を防止できます。

しかし、この動作はAPI固有です。Idempotency-Keyヘッダーを追加するだけでは、任意のAPIが自動的に冪等的になるわけではありません。

支払い、注文、サブスクリプション、データベース変更を伴う操作については、プロバイダーの公式リトライおよび冪等性ドキュメントに従ってください。

冪等性メカニズムが存在しない場合、再試行する前に操作のステータスを照会したり、結果を調整したりする必要があるかもしれません。

7. 長時間実行されるWebリクエスト内でスリープを避ける

Technical workflow illustration

この例では、リトライ動作を理解しやすくするためにusleep()を使用しています。

これは、厳密に制御されたリトライ予算を持つ短い操作では許容できる場合があります。

しかし、本番Webサイトでは、外部APIを待機している間、PHPワーカーを数分間占有すべきではありません。

APIが以下のように応答するとします:

HTTP/1.1 429 Too Many Requests
Retry-After: 3600

HTTPリクエスト内で1時間待機することは、悪い設計です。

より良い解決策は、操作を延期することです。

例として、保留中のジョブを保存します:

Job ID: 1842
Status: pending
Attempts: 2
Next attempt: 2026-11-20 14:30:00 UTC

スケジュールされたワーカーが、ジョブが実行可能になったときに処理できます。

このアプローチは特に以下で有用です:

  • 商品カタログの同期。
  • メール配信。
  • ソーシャルメディア投稿。
  • ドキュメント処理。
  • 在庫更新。
  • 大量APIインポート。

また、失敗の監視と復旧も容易になります。

8. リトライ情報をデータベースに保存する

MariaDBベースのアプリケーションの場合、シンプルなジョブテーブルは次のようになります:

CREATE TABLE api_jobs (
    id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
    job_type VARCHAR(100) NOT NULL,
    payload_json LONGTEXT NOT NULL,
    status VARCHAR(20) NOT NULL DEFAULT 'pending',
    attempts INT UNSIGNED NOT NULL DEFAULT 0,
    next_attempt_at DATETIME NOT NULL,
    last_error TEXT NULL,
    created_at DATETIME NOT NULL,
    updated_at DATETIME NOT NULL,
    INDEX idx_jobs_ready (
        status,
        next_attempt_at
    )
);

ワーカーは以下の条件でジョブを選択します:

SELECT id, job_type, payload_json
FROM api_jobs
WHERE status = 'pending'
AND next_attempt_at <= UTC_TIMESTAMP()
ORDER BY next_attempt_at, id
LIMIT 20;

これはキュー実装の選択部分のみです。

複数のワーカーが同時に実行される場合、ジョブは適切なトランザクションとロック戦略を使用してアトミックに取得し、重複処理を防止する必要があります。

ワーカーはまた、最大リトライ回数を適用し、永続的に失敗するジョブを調査が必要な状態に移動させるべきです。

小規模なアプリケーションでは、Redisや専用のメッセージブローカーを導入せずに、このデータベースベースのアプローチで十分な場合があります。

9. 機密データを露出せずに失敗をログ記録する

有用なAPIログは、以下の4つの質問に答えるべきです:

  1. どの操作が失敗したか?
  2. どのリモートサービスが関与していたか?
  3. HTTPステータスまたはトランスポートエラーは何か?
  4. アプリケーションはいつリトライするか?

例:

[2026-11-20 13:25:00 UTC]
service=inventory-api
operation=sync-products
status=429
attempt=2
next_retry=2026-11-20T13:26:00Z

APIキー、ベアラートークン、完全な認証ヘッダー、パスワード、不要な個人情報をログに記録しないでください。

リクエストを相関させる必要がある場合は、生成されたリクエスト識別子を使用してください。

例:

$requestId = bin2hex(random_bytes(8));

この識別子をアプリケーションログに含め、サポートされている場合はリモートAPIに送信できます。

10. 本番環境前にリトライ戦略をテストする

リトライメカニズムは、予測可能な障害シナリオでテストすべきです。

実際のAPI障害を待つ必要はありません。

ローカルテストエンドポイントで、意図的に特定のステータスコードを返すようにできます。

例:

<?php
declare(strict_types=1);

header('Content-Type: application/json');

http_response_code(429);
header('Retry-After: 3');

echo json_encode([
    'error' => 'rate_limit_exceeded',
]);

このエンドポイントは、ローカルまたは保護されたテスト環境でのみ実行してください。

その後、クライアントが以下を行うことを確認します:

  • HTTP 429を検出する。
  • Retry-Afterヘッダーを読み取る。
  • リトライ前に待機する。
  • 設定された試行回数後に停止する。
  • シークレットを露出せずに失敗を記録する。

HTTP 503と意図的に遅いエンドポイントでも繰り返してください。

また、HTTP 400レスポンスでテストし、クライアントが永続的なリクエストエラーをリトライしないことを確認してください。

最後に、接続が失敗する前に操作が成功していた可能性がある操作をテストしてください。これは支払いと注文の統合にとって不可欠です。

11. 信頼できるAPI統合のための本番チェックリスト

API統合をデプロイする前に、以下を確認してください:

チェック 期待される動作
接続タイムアウト 定義され、テスト済み
全体タイムアウト 定義され、テスト済み
HTTP 429 レート制限を尊重
HTTP 5xx 選択的にリトライ
HTTP 4xx 無闇なリトライなし
リトライ上限 無限ループを防止
リトライ遅延 ジッター付きバックオフ
POST操作 冪等性または調整
長い待機期間 ワーカーに延期
ログ 有用、プライベート、サニタイズ済み
ワーカー並行性 重複実行防止
永続的障害 可視化可能、復旧可能

結論:信頼できるAPIには制御された障害処理が必要

外部APIは決して完璧に利用可能ではありません。

よくメンテナンスされているサービスでも、一時的な過負荷、ネットワーク中断、レート制限を経験する可能性があります。

目標はすべての障害を排除することではありません。障害が発生したときに、アプリケーションが予測可能に応答するようにすることです。

適切なタイムアウトと明示的なHTTPエラー処理から始めましょう。境界付きリトライと指数バックオフを追加し、サーバー提供のリトライ遅延を尊重し、重複データを作成する可能性のある操作を自動的に繰り返さないようにします。

より複雑な統合では、Webリクエストを開いたままにする代わりに、リトライを永続的なジョブキューに移動させます。

これらの原則は、CMS拡張機能の構築、Eコマースカタログの同期、トランザクションメールの送信、決済サービスの統合など、ほぼすべての最新PHPアプリケーションに適用されます。

信頼できるAPIクライアントとは、リクエストを送信する方法だけでなく、いつリトライし、いつ待機し、いつ停止するかを知っているものです。

公式リファレンス