Skip to main content
Blue Moose logo Blue Moose Field notes
← All articles
code

Retry flaky APIs in Symfony HttpClient and test it

Code on a dark editor screen

The first time a third-party API bit me in production, it wasn't an outage. It was a single 503 at the wrong moment: a nightly sync that fetched exchange rates died halfway, and nobody noticed until the invoices were wrong. The fix was not a bigger try/catch. It was letting the HTTP client retry the way a polite client should, and having a test that proves it does.

Symfony's HttpClient component ships both halves: RetryableHttpClient for the retries and MockHttpClient for the test. Here is the setup I now copy into every project, and it works the same inside a Drupal module that has symfony/http-client installed via Composer.

Build a client that retries sensibly

RetryableHttpClient decorates any HttpClientInterface. Its constructor takes the inner client, an optional RetryStrategyInterface, the max number of retries (default 3) and an optional logger. The stock GenericRetryStrategy takes a list of status codes, an initial delay in milliseconds, a multiplier, a max delay and a jitter factor. In the status-code list, a plain value means "always retry", while a key mapped to an array of HTTP methods means "retry only for those methods".

<?php

declare(strict_types=1);

namespace App\Rates;

use Symfony\Component\HttpClient\HttpClient;
use Symfony\Component\HttpClient\Retry\GenericRetryStrategy;
use Symfony\Component\HttpClient\RetryableHttpClient;
use Symfony\Contracts\HttpClient\HttpClientInterface;

final class RatesClientFactory
{
    public static function create(string $baseUri): HttpClientInterface
    {
        $inner = HttpClient::create([
            'base_uri' => $baseUri,
            'timeout' => 3,
            'headers' => ['Accept' => 'application/json'],
        ]);

        $strategy = new GenericRetryStrategy(
            // 0 = transport errors, retried for GET only; the rest always.
            statusCodes: [0 => ['GET'], 429, 502, 503, 504],
            delayMs: 500,
            multiplier: 2.0,
            maxDelayMs: 4000,
            jitter: 0.2,
        );

        return new RetryableHttpClient($inner, $strategy, 3);
    }
}

With these numbers the waits are roughly 0.5s, 1s and 2s, with 20% jitter so a fleet of workers doesn't hammer the API in lockstep. If the server sends a Retry-After header, RetryableHttpClient reads it first and only falls back to the strategy's delay when the header is absent.

Keep the consumer boring

The consuming class only knows HttpClientInterface. It doesn't know retries exist, which is the whole point.

<?php

declare(strict_types=1);

namespace App\Rates;

use Symfony\Contracts\HttpClient\HttpClientInterface;

final class ExchangeRateClient
{
    public function __construct(private readonly HttpClientInterface $client)
    {
    }

    public function rate(string $from, string $to): float
    {
        $response = $this->client->request('GET', '/v1/rates', [
            'query' => ['base' => $from, 'symbols' => $to],
        ]);

        // toArray() throws on 4xx/5xx once retries are exhausted.
        $data = $response->toArray();

        if (!isset($data['rates'][$to])) {
            throw new \UnexpectedValueException("No rate for $from/$to in response.");
        }

        return (float) $data['rates'][$to];
    }
}

Prove it with MockHttpClient

MockHttpClient accepts an iterable of MockResponse objects and serves them in order, and getRequestsCount() tells you how many requests it actually received. Wrap it in the same decorator, but with a zero-millisecond delay so the test doesn't sleep.

<?php

declare(strict_types=1);

namespace App\Tests;

use App\Rates\ExchangeRateClient;
use PHPUnit\Framework\TestCase;
use Symfony\Component\HttpClient\MockHttpClient;
use Symfony\Component\HttpClient\Response\MockResponse;
use Symfony\Component\HttpClient\Retry\GenericRetryStrategy;
use Symfony\Component\HttpClient\RetryableHttpClient;

final class ExchangeRateClientTest extends TestCase
{
    public function testRetriesTransient503ThenSucceeds(): void
    {
        $mock = new MockHttpClient([
            new MockResponse('', ['http_code' => 503]),
            new MockResponse('', ['http_code' => 503]),
            new MockResponse('{"rates":{"USD":1.08}}', ['http_code' => 200]),
        ], 'https://rates.test');

        $client = new RetryableHttpClient(
            $mock,
            new GenericRetryStrategy(statusCodes: [503], delayMs: 0, jitter: 0.0),
            3,
        );

        $rate = (new ExchangeRateClient($client))->rate('EUR', 'USD');

        $this->assertSame(1.08, $rate);
        $this->assertSame(3, $mock->getRequestsCount());
    }
}

Two failures, one success, three requests on the wire. If someone later narrows the status list or drops the decorator, this test goes red instead of your sync job going quiet at 3 a.m.

Where this bites

Retrying is only safe for idempotent calls. I deliberately limited transport-error retries to GET; a retried POST that created an order the first time is a bug you will spend a week chasing. Also remember worst-case latency: three retries on a 3-second timeout plus backoff can hold a request open for well over ten seconds, which is fine in a queue worker and a bad idea inside a page render. Use this in background jobs, and fail fast on the front end.

BM
Blue Moose
The moose behind Blue Moose. Full-stack PHP developer — Drupal by day, Symfony by night, tests always.