Технологічна галузь

Як обробляти таймаути 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 перериває синхронізацію.

Спокуса — негайно повторити запит.

Але повторення без стратегії може погіршити проблему. Воно може перевантажити API, який уже ледве справляється, перевищити обмеження частоти запитів або випадково створити дубльовані замовлення й платежі.

Надійному API-клієнту потрібно більше, ніж успішний виклик curl_exec().

У цьому посібнику ми створимо практичний PHP HTTP-клієнт, який обробляє тайм-аути з'єднання, HTTP-помилки, обмеження частоти запитів і тимчасові збої. Ми також пояснимо, коли повторення є безпечним, коли ні, і як діагностувати проблеми у виробничому середовищі.

У прикладах використовується вбудоване розширення cURL для PHP, без Composer або сторонніх залежностей.

1. Розумійте різні типи збоїв API

Не кожен неуспішний запит слід обробляти однаково.

Збій Типова причина Рекомендована дія
Тайм-аут з'єднання Сервер недоступний або повільне з'єднання Повторювати обережно
HTTP 400 Недійсні параметри запиту Виправте запит
HTTP 401 Недійсні або прострочені облікові дані Перевірте автентифікацію
HTTP 404 Ресурс не знайдено Перевірте ідентифікатор ресурсу
HTTP 429 Перевищено обмеження частоти запитів API Дотримуйтеся Retry-After
HTTP 500 Внутрішня помилка сервера Повторювати вибірково
HTTP 503 Тимчасова недоступність сервісу Повторіть із затримкою
Invalid 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 секунд

Замість повторення щосекунди застосунок чекає дедалі довше.

Додавання невеликої випадкової варіації, званої 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
    );
}

Вона використовує повний jitter: фактична затримка випадково вибирається між нулем і експоненційною верхньою межею.

Випадкова затримка зменшує синхронізовані сплески повторних спроб, хоча це не замінює явну інструкцію 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());
}

Ця реалізація навмисно обмежена GET-запитами до довірених кінцевих точок API.

Вона не повторює автоматично операції 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. Уникайте сну всередині довготривалих веб-запитів

Technical workflow illustration

У нашому прикладі використовується usleep(), щоб поведінку повторних спроб було легко зрозуміти.

Це може бути прийнятним для коротких операцій із жорстко контрольованим бюджетом повторних спроб.

Однак виробничий вебсайт не повинен займати PHP-воркери на хвилини, очікуючи зовнішній API.

Припустімо, 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 має відповідати на чотири запитання:

  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-ключів, 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 Без сліпих повторних спроб
Ліміт повторних спроб Запобігає нескінченним циклам
Затримка перед повторною спробою Затримка з jitter
Операції POST Ідемпотентність або звіряння
Довгі періоди очікування Відкладаються на воркер
Журнали Корисні, приватні, очищені
Паралельність воркерів Запобігає дублюванню виконання
Постійні збої Видимі та відновлювані

Висновок: надійні API потребують контрольованої обробки збоїв

Зовнішні API ніколи не бувають ідеально доступними.

Навіть добре підтримуваний сервіс може зазнавати тимчасового перевантаження, мережевих перебоїв або обмеження частоти запитів.

Мета не в тому, щоб усунути кожен збій. Мета — зробити так, щоб ваш застосунок передбачувано реагував, коли збої трапляються.

Почніть із розумних тайм-аутів і явної обробки HTTP-помилок. Додайте обмежені повторні спроби з експоненційним збільшенням затримки, дотримуйтеся затримок повторних спроб, наданих сервером, і уникайте автоматичного повторення операцій, які можуть створювати дубльовані дані.

Для складніших інтеграцій перенесіть повторні спроби в постійну чергу завдань замість того, щоб тримати веб-запити відкритими.

Ці принципи застосовні майже до кожного сучасного PHP-застосунку, незалежно від того, чи ви створюєте розширення CMS, синхронізуєте каталог електронної комерції, надсилаєте транзакційні електронні листи чи інтегруєте платіжний сервіс.

Надійний API-клієнт — це той, що знає не лише, як надіслати запит, а й коли повторювати спробу, коли чекати, а коли зупинитися.

Офіційні джерела