Как обрабатывать тайм‑ауты API, лимиты запросов и повторные попытки в PHP
Узнайте, как создавать надёжные интеграции PHP API с тайм‑аутами соединения, обработкой ошибок HTTP, экспоненциальным откатом, поддержкой Retry-After и безопасными стратегиями повторных попыток.
Как обрабатывать таймауты API, ограничения скорости и повторные попытки в PHP
Интеграция API работает идеально во время разработки. Затем, однажды, запланированная задача останавливается посередине. Удаленный сервис возвращает HTTP 429, таймаут соединения или ошибка HTTP 503 прерывает синхронизацию.
Импульс — сразу повторить запрос. Но повторение запроса без стратегии может усугубить проблему. Оно может перегрузить уже struggling API, превысить лимиты скорости или случайно создать дублирующиеся заказы и платежи.
Надежный клиент API требует больше, чем успешный вызов curl_exec().
В этом уроке мы построим практичный PHP-клиент HTTP, который обрабатывает таймауты соединения, ошибки HTTP, ограничения скорости и временные сбои. Мы также объясним, когда безопасно повторять, когда нельзя, и как диагностировать проблемы в production.
Примеры используют встроенную расширение cURL PHP, без 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
Клиент, хорошо поведеный, должен уважать это указание, вместо повторной отправки запросов.
Если сервер не предоставляет задержку повтора, вашему приложению нужна стратегия fallback.
4. Использовать экспоненциальную задержку вместо немедленных повторов
Экспоненциальная задержка увеличивает время ожидания после successive сбоев.
Пример:
| Повтор | Пример задержки |
|---|---|
| 1 | 1 секунда |
| 2 | 2 секунды |
| 3 | 4 секунды |
| 4 | 8 секунд |
Вместо повторения запроса каждую секунду приложение ждет progressively longer.
Добавление небольшого случайного вариации, называемой jitter, помогает предотвратить одновременное повторение запросов многими клиентами.
Вот переиспользуемая функция задержки:
<?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
);
}
Это использует full jitter: фактическая задержка случайно выбирается между нулем и экспоненциальным пределом.
Случайная задержка сокращает синхронные bursts повторений, though и не заменяет явное инструкции сервера Retry-After.
5. Построить переиспользуемый PHP-клиент API
Давайте объединим предыдущие концепции в работающую реализацию.
Наш клиент будет:
- Устанавливать таймауты соединения и overall request.
- Возвращать 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());
}
Эта реализация намеренно ограничена GET-запросами к надежным точкам ending API.
Она не автоматически повторят POST, PUT, PATCH или DELETE операции, так как эти требуют дополнительных мер защиты.
Она также возвращает non-retryable HTTP ответы вызову, который должен решить, как их обработать.
Для production-систем вы также должны валидировать типы ответов, принуждать ограничения размера ответа и Distinguished транспортные ошибки повторения от permanent TLS или configuration failures.
6. Почему повторение POST-запросов может быть опасным
Представьте приложение ecommerce, отправляющее этот запрос:
POST /api/orders
Content-Type: application/json
{
"product_id": 42,
"quantity": 1
}
Удаленный API создает заказ, но соединение падает перед получением вашим приложением ответа.
Ваше приложение видит таймаут.
Зафейлился заказ?
Не обязательно. Заказ уже может существовать.
Если ваше приложение сразу повторит, оно может создать второй заказ.
Это почему таймаут не доказательство, что операция провалилась на сервере.
Использовать ключи идемпотентности некоторые API поддерживают
Пример:
Idempotency-Key: order-8f7a2c
Когда API предоставляет документированный механизм идемпотентности, повторение той же логической операции с использованием того же ключа может предотвратить двойную обработку.
Но это поведение зависит от API. Добавление Idempotency-Key заголовка не автоматически делает любой API идемпотентным.
Для операций, связанных с платежами, заказами, подписками или модификацией базы данных, следуйте официальной документации провайдера по поводу повторов и идемпотентности.
Когда нет механизма идемпотентности, вам, возможно, нужно будет запросить статус операции или reconcile результаты перед повторной попыткой.
7. Избегать сна inside long-running web requests

Наш пример использует usleep() чтобы сделать поведение retry легко понятным.
Это может быть приемлемо для коротких операций с tightly controlled retry budget.
Однако production-сайт не должен занимать рабочих PHP минут ожидания внешнего API.
Представьте, что API отвечает с:
HTTP/1.1 429 Too Many Requests
Retry-After: 3600
Ожидание часа inside HTTP-запроса была бы плохим дизайном.
Лучшее решение — отложить операцию.
Пример, хранить pending job:
Job ID: 1842
Status: pending
Attempts: 2
Next attempt: 2026-11-20 14:30:00 UTC
Планировщик-worker может затем обрабатывать job, когда станет допустимым.
Этот подход especialmente полезен для:
- Синхронизация каталога продукта.
- Email доставка.
- Social media publishing.
- Document processing.
- Инвентарные обновления.
- Large API imports.
Это также облегчает мониторинг сбоев и восстановление.
8. Хранить информацию о повторениях в базе данных
Для приложения на MariaDB простая таблица jobs могла бы выглядеть так:
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
)
);
Worker выбирает jobs где:
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;
Это только часть selection реализации очереди.
Если несколько workers могут выполняться одновременно, jobs должны быть claimed atomically, используя appropriate transaction and locking strategy, чтобы предотвратить duplicate processing.
Worker также должен применять максимальный count retry и перемещать permanently failing jobs в состояние requiring investigation.
Для небольшого приложения эта база данных может быть достаточной без введения Redis или выделенного брокера сообщений.
9. Логировать сбои без exponing sensitive data
Полезный лог API должен отвечать на четыре вопроса:
- Какая операция провалилась?
- Какой удаленный сервис был вовлечен?
- Какой был HTTP статус или транспортная ошибка?
- Когда application будет retry?
Пример:
[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 keys, bearer tokens, полные authorization headers, passwords, или unnecessary personal information.
Если вам нужно коррелировать запросы, используйте сгенерированный request identifier.
Пример:
$requestId = bin2hex(random_bytes(8));
Вы можете включить этот идентификатор в application logs и, когда поддерживается, отправить его удаленному API.
10. Протестируйте стратегию повторения перед production
Механизм повторения должен быть протестирован against predictable failure scenarios.
You don't need to wait for a real API outage.
Local test endpoint can deliberately return specific status codes.
Пример:
<?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',
]);
Запустите этот endpoint только в local или protected test environment.
Then verify that your client:
- Detects HTTP 429.
- Reads the
Retry-Afterheader. - Waits before retrying.
- Stops after the configured number of attempts.
- Records the failure without exposing secrets.
Repeat with HTTP 503 and a deliberately slow endpoint.
Also test an HTTP 400 response to confirm that the client doesn't retry permanent request errors.
Finally, test an operation that may have succeeded before the connection failed. This is essential for payment and order integrations.
11. Чек-лист production для надежных API-интеграций
Перед деплоем API-интеграции,.verify the following:
| Check | Expected behavior |
|---|---|
| Connection timeout | Defined and tested |
| Overall timeout | Defined and tested |
| HTTP 429 | Respects rate limits |
| HTTP 5xx | Retries selectively |
| HTTP 4xx | No blind retries |
| Retry limit | Prevents endless loops |
| Retry delay | Backoff with jitter |
| POST operations | Idempotency or reconciliation |
| Long waiting periods | Deferred to a worker |
| Logs | Useful, private, sanitized |
| Worker concurrency | Duplicate execution prevented |
| Permanent failures | Visible and recoverable |
Вывод: надежные API требуют controlled failure handling
Внешние API никогда не бывают perfectly available.
Даже хорошо обслуженный сервис может испытывать временную перегрузку, сетевые прерывания или ограничение скорости.
Goal isn't to eliminate every failure. It's to make your application respond predictably when failures happen.
Start with sensible timeouts and explicit HTTP error handling. Add bounded retries with exponential backoff, respect server-provided retry delays, and avoid automatically repeating operations that could create duplicate data.
For more complex integrations, move retries into a persistent job queue instead of keeping web requests open.
These principles apply to almost every modern PHP application, whether you're building a CMS extension, synchronizing an ecommerce catalog, sending transactional emails, or integrating a payment service.
Надежный клиент API — это тот, который знает не только how to send a request, but also when to retry, when to wait, and when to stop.
Официальные ссылки
- PHP Manual — curl_setopt()
- PHP Manual — cURL options and constants
- MDN — HTTP 429 Too Many Requests
- MDN — Retry-After header
