PHPでAPIタイムアウト、レートリミット、リトライを処理する方法
接続タイムアウト、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指示に取って代わるものではありません。

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リクエスト内でスリープを避ける

この例では、リトライ動作を理解しやすくするために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つの質問に答えるべきです:
- どの操作が失敗したか?
- どのリモートサービスが関与していたか?
- HTTPステータスまたはトランスポートエラーは何か?
- アプリケーションはいつリトライするか?
例:
[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クライアントとは、リクエストを送信する方法だけでなく、いつリトライし、いつ待機し、いつ停止するかを知っているものです。