Як правильно викликати сторонній API через HTTP-клієнт Laravel: тайм-аути й обробка помилок?

HTTP-клієнт Laravel (обгортка над Guzzle) робить запити до сторонніх API коротко й зручно:

use Illuminate\Support\Facades\Http;

$response = Http::withToken(config('services.nova_poshta.key'))
    ->acceptJson()
    ->connectTimeout(3)
    ->timeout(10)
    ->get('https://api.example.com/v1/parcels/123');

$status = $response->json('data.status');

Тайм-аути - обов'язкові для свідомого вибору:

• connectTimeout - скільки чекати на встановлення з'єднання (за замовчуванням 10 секунд);
• timeout - скільки чекати на всю відповідь (за замовчуванням 30 секунд).

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

Помилки - клієнт не кидає винятки сам. Відповідь 404 чи 500 - це звичайний об'єкт Response, і код спокійно продовжить роботу з порожніми даними. Перевіряйте явно:

if ($response->failed()) {            // 4xx або 5xx
    // ...
}

$response->successful();   // 2xx
$response->clientError();  // 4xx
$response->serverError();  // 5xx

$data = $response->throw()->json();   // кинути RequestException на 4xx/5xx

Два різні типи збою:

• Illuminate\Http\Client\RequestException - сервер відповів з помилкою (throw());
• Illuminate\Http\Client\ConnectionException - відповіді не було взагалі: тайм-аут, DNS, відмова в з'єднанні. Кидається завжди.

Що ще варто зробити відразу:

• ключі й адреси - у config/services.php з .env, не в коді;
• базову адресу й автентифікацію зібрати в одному місці (макрос або клас-клієнт), щоб не дублювати по проєкту;
• логувати збої з контекстом (ендпойнт, статус, ідентифікатор запиту), але без токенів і персональних даних;
• не довіряти формату відповіді: сторонній API може змінити поле - $response->json('data.status') поверне null, і це треба обробити.

Довгі чи масові виклики - у черзі, а не в запиті користувача.

Докладніше в документації: HTTP-клієнт: тайм-аути