Технологическая отрасль

Как обрабатывать тайм‑ауты API, лимиты запросов и повторные попытки в PHP

How to Handle API Timeouts, Rate Limits, and Retries in 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

Technical workflow illustration

Наш пример использует 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 должен отвечать на четыре вопроса:

  1. Какая операция провалилась?
  2. Какой удаленный сервис был вовлечен?
  3. Какой был HTTP статус или транспортная ошибка?
  4. Когда 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-After header.
  • 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.

Официальные ссылки

Illustration of the article's main concept