如何在 PHP 中处理 API 超时、速率限制和重试
学习如何使用连接超时、HTTP 错误处理、指数退避、Retry-After 支持以及安全重试策略,构建可靠的 PHP API 集成
API 集成在开发期间运行完美。然后,有一天,你的定时任务中途停止。远程服务返回 HTTP 429,连接超时,或者 HTTP 503 错误中断了同步。
人们很容易想立即重试请求。
但没有策略地重试可能会让问题更糟。它可能使本已吃力的 API 过载、超出速率限制,或意外创建重复的订单和支付。
可靠的 API 客户端需要的不仅仅是一次成功的 curl_exec() 调用。
在本教程中,我们将构建一个实用的 PHP HTTP 客户端,用于处理连接超时、HTTP 错误、速率限制和临时失败。我们还会解释何时重试是安全的、何时不安全,以及如何在生产环境中诊断问题。
这些示例使用 PHP 内置的 cURL 扩展,不依赖 Composer 或第三方依赖。
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 提供了两个特别有用的设置:
CURLOPT_CONNECTTIMEOUT => 5,
CURLOPT_TIMEOUT => 15,
CURLOPT_CONNECTTIMEOUT 限制连接阶段,而 CURLOPT_TIMEOUT 限制整个传输持续时间。两者都在 PHP 官方 cURL 参考文档中有说明。
如果没有适当的限制,缓慢的外部服务可能会让 PHP 工作进程被占用远超预期的时间。
对于常规 JSON API,一个实用的起点可能是连接建立用五秒,完整请求用十五秒。
这些并非通用值。文件上传或长时间运行的报告生成可能需要不同的超时策略。
发起你的第一个 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 请求可能很危险
想象一个电子商务应用发送此请求:
POST /api/orders
Content-Type: application/json
{
"product_id": 42,
"quantity": 1
}
远程 API 创建了订单,但连接在你的应用收到响应之前中断了。
你的应用看到超时。
订单失败了吗?
不一定。订单可能已经存在。
如果你的应用立即重试,它可能会创建第二个订单。
这就是为什么超时并不证明操作在服务器上失败了。
在受支持时使用幂等键
有些 API 支持幂等键。
例如:
Idempotency-Key: order-8f7a2c
当 API 提供了有文档说明的幂等机制时,对同一逻辑操作的重试复用同一个键可以防止重复处理。
但这种行为因 API 而异。添加 Idempotency-Key 请求头并不会自动让任意 API 变成幂等的。
对于涉及支付、订单、订阅或数据库修改的操作,请遵循提供方的官方重试和幂等性文档。
当不存在幂等机制时,你可能需要在再次尝试之前查询操作状态或核对结果。
7. 避免在长时间运行的 Web 请求内休眠

我们的示例使用 usleep() 让重试行为易于理解。
对于时间短且重试预算严格受控的操作,这可以接受。
然而,生产网站不应在等待外部 API 时让 PHP 工作进程被占用数分钟。
假设 API 返回:
HTTP/1.1 429 Too Many Requests
Retry-After: 3600
在 HTTP 请求内等待一小时会是很糟糕的设计。
更好的解决方案是延迟该操作。
例如,存储一个待处理任务:
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 日志应回答四个问题:
- 哪个操作失败了?
- 涉及哪个远程服务?
- 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 密钥、Bearer 令牌、完整授权头、密码或不必要的个人信息。
如果你需要关联请求,请使用生成的请求标识符。
例如:
$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 请求打开。
这些原则几乎适用于所有现代 PHP 应用,无论你是在构建 CMS 扩展、同步电子商务目录、发送事务性电子邮件,还是集成支付服务。
可靠的 API 客户端不仅知道如何发送请求,还知道何时重试、何时等待以及何时停止。