Web ve Geliştirme

API Zaman Aşımalarını, Oran Sınırlarını ve Yeniden Denemeleri PHP'de Nasıl Ele Alınır

How to Handle API Timeouts, Rate Limits, and Retries in PHP

Bağlantı zaman aşımı, HTTP hata işleme, üssel geri çekme, Retry-After desteği ve güvenli yeniden deneme stratejileri ile güvenilir PHP API entegrasyonları nasıl oluşturulur öğrenin.

PHP'de API Zaman Aşımı, Hız Sınırları ve Yeniden Deneme İşlemlerinin Yönetimi

Bir API entegrasyonu geliştirme sırasında mükemmel çalışır. Daha sonra, bir gün, zamanlanmış görevleriniz yarımda kalır. Uzak bir hizmet HTTP 429 yanıtı verir, bir bağlantı zaman aşımına uğrar veya bir HTTP 503 hatası bir senkronizasyonu kesintiye uğratır.

İsteği hemen yeniden deneme isteği doğar.

Ancak strateji olmadan yeniden deneme sorunu kötüleştirebilir. Zaten zorlanan bir API'yi aşırı yükleyebilir, hız sınırlarını aşıp veya yanlışlıkla yinelenen sipariş ve ödeme oluşturabilir.

Güvenilir bir API istemcisi, başarılı bir curl_exec() çağrısından daha fazlasına ihtiyaç duyar.

Bu eğitimde, bağlantı zaman aşımlarını, HTTP hatalarını, hız sınırlarını ve geçici hataları yöneten pratik bir PHP HTTP istemcisi oluşturacağız. Ayrıca, yeniden denemenin ne zaman güvenli olduğunu, ne zaman olmadığını ve üretim ortamındaki sorunları nasıl teşhis edeceğimizi açıklayacağız.

Örnekler, Composer veya üçüncü taraf bağımlılıkları olmadan PHP'nin yerleşik cURL uzantısını kullanır.

1. Farklı API hata türlerini anlama

Her başarısız istek aynı şekilde ele alınmamalıdır.

Hata Tipik neden Önerilen eylem
Bağlantı zaman aşımı Sunucuya erişilemiyor veya yavaş bağlantı Dikkatli yeniden dene
HTTP 400 Geçersiz istek parametreleri İsteği düzelt
HTTP 401 Geçersiz veya süresi dolmuş kimlik bilgileri Kimlik doğrulamayı kontrol et
HTTP 404 Kaynak bulunamadı Kaynak tanımlayıcısını kontrol et
HTTP 429 API hız sınırı aşıldı Retry-After saygı göster
HTTP 500 Dahili sunucu hatası Seçici yeniden dene
HTTP 503 Geçici hizmet kullanılamazlığı Gecikmeyle yeniden dene
Geçersiz JSON Beklenmeyen yanıt formatı Kaydet ve incele

Bir ağ hatası, bir HTTP hatasından da farklıdır.

Bir API HTTP 500 döndürdüğünde, HTTP isteği tamamlanmış ve sunucu bir hata yanıtı vermiştir.

cURL bir bağlantı hatası bildirdiğinde, uygulamanız hiçbir HTTP yanıtı almamış olabilir.

Bu ayrım, yeniden deneme kararı verirken önemlidir.

2. Her zaman bağlantı ve istek zaman aşımlarını yapılandırın

PHP cURL, iki özellikle yararlı ayar sağlar:

CURLOPT_CONNECTTIMEOUT => 5,
CURLOPT_TIMEOUT => 15,

CURLOPT_CONNECTTIMEOUT bağlantı aşamasını sınırlarken, CURLOPT_TIMEOUT genel aktarım süresini sınırlar. Her ikisi de PHP'nin resmi cURL referansında belgelenmiştir.

Uygun sınırlar olmadan, yavaş bir harici hizmet PHP çalışanlarını beklenenin çok ötesinde süreler için meşgul edebilir.

Geleneksel bir JSON API'si için pratik bir başlangıç noktası, bağlantı kurma için beş saniye ve tam istek için on beş saniye olabilir.

Bu evrensel değerler değildir. Dosya yükleme veya uzun süren rapor oluşturma farklı bir zaman aşımı politikasına ihtiyaç duyabilir.

İlk API isteğinizi yapın

<?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;

Bu faydalı bir temel oluşturur, ancak henüz hız sınırlarını veya yeniden denenebilir hataları yönetmez.

3. HTTP 429 ve Retry-After'ı anlama

HTTP 429, istemcinin API sağlayıcısı tarafından tanımlanan bir dönem içinde çok fazla istek gönderdiği anlamına gelir.

Bazı API'ler dakika başına, saat başına, API anahtarı başına veya hesap başına sınırlar koyar.

Bir sunucu şu şekilde yanıt verebilir:

HTTP/1.1 429 Too Many Requests
Retry-After: 60
Content-Type: application/json

Retry-After başlığı, istemciye tekrar denemeden önce ne kadar beklemesi gerektiğini söyler.

Bu başlık ya saniye sayısı ya da bir HTTP tarihi içerebilir.

Örneğin:

Retry-After: 120

Ya da:

Retry-After: Wed, 25 Nov 2026 10:00:00 GMT

Davranışı iyi bir istemci, tekrar tekrar istek göndermek yerine bu talimatı saygı duymalıdır.

Sunucu bir yeniden deneme gecikmesi sağlamazsa, uygulamanız bir yedek stratejiye ihtiyaç duyar.

4. Hemen yeniden deneme yerine üstel geri çekilme kullanın

Üstel geri çekilme, ardışık hatalar sonrası bekleme süresini artırır.

Örneğin:

Yeniden Deneme Örnek gecikme
1 1 saniye
2 2 saniye
3 4 saniye
4 8 saniye

Her saniye yeniden deneme yerine, uygulama kademeli olarak daha uzun bekler.

Küçük bir rasgele varyasyon eklemek, jitter denir ve birçok istemcinin aynı anda yeniden denemesini önlemeye yardımcı olur.

İşte yeniden kullanılabilir bir gecikme fonksiyonu:

<?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
    );
}

Bu tam jitter kullanır: gerçek gecikme, sıfır ve üstel üst sınır arasında rastgele seçilir.

Rastgele gecikme, senkronize yeniden deneme patlamalarını azaltır, ancak açıkça sunucu tarafından sağlanan Retry-After talimatının yerini almaz.

Illustration of the article's main concept

5. Yeniden kullanılabilir bir PHP API istemcisi oluşturun

Önceki kavramları çalışan bir uygulamada birleştirelim.

İstemcimiz şunları yapacak:

  • Bağlantı ve genel istek zaman aşımlarını ayarla.
  • HTTP durumunu ve yanıt gövdesini döndür.
  • Taşıma hatalarını tespit et.
  • Seçili geçici hataları yeniden dene.
  • Mevcut olduğunda Retry-After saygı göster.
  • Deneme sayısını sınırla.
  • Etkisiz olmayan işlemleri otomatik olarak yeniden denemeyi engelle.
<?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.'
    );
}

Nasıl kullanılır

<?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());
}

Bu uygulama, güvenilir API uç noktalarına karşı GET istekleriyle kasıtlı olarak sınırlandırılmıştır.

POST, PUT, PATCH veya DELETE işlemlerini otomatik olarak yeniden denemez, çünkü bunlar ek koruma önlemleri gerektirir.

Ayrıca, yeniden denenemeyen HTTP yanıtlarını çağırana döndürür ve çağıranın bunları nasıl ele alacağına karar vermesi gerekir.

Üretim sistemleri için, yanıt türlerini de doğrulamalısınız, yanıt boyutu sınırlarını zorunlu kılmalı ve yeniden denenebilir taşıma hatalarını kalıcı TLS veya yapılandırma hatalarından ayırt etmelisiniz.

6. POST isteklerinin yeniden denenesi neden tehlikeli olabilir

Bir e-ticaret uygulamasının şu isteği gönderdiğini hayal edin:

POST /api/orders
Content-Type: application/json

{
  "product_id": 42,
  "quantity": 1
}

Uzak API siparişi oluşturur, ancak bağlantı uygulamanız yanıtı almadan önce kopar.

Uygulamanız bir zaman aşımı görür.

Sipariş başarısız oldu mu?

Zorunlu değil. Sipariş zaten var olabilir.

Uygulamanız hemen yeniden denerse, ikinci bir sipariş oluşturmuş olabilir.

Bu nedenle bir zaman aşımı, sunucuda bir işlemin başarısız olduğunu kanıtlamaz.

Desteklendiğinde etkisizlik anahtarlarını kullanın

Bazı API'ler etkisizlik anahtarlarını destekler.

Örneğin:

Idempotency-Key: order-8f7a2c

API belgelenmiş bir etkisizlik mekanizması sağladığında, aynı mantıksal işlemin yeniden denemeleri için aynı anahtarı yeniden kullanmak yinelenen işleme engel olabilir.

Ancak bu davranış API'ye özgüdür. Bir Idempotency-Key başlığı eklemek, keyfi bir API'yi otomatik olarak etkisiz hale getirmez.

Ödemeler, siparişler, abonelikler veya veritabanı değişiklikleri içeren işlemler için, sağlayıcının resmi yeniden deneme ve etkisizlik belgelerini takip edin.

Etkisizlik mekanizması yoksa, tekrar denemeden önce işlemin durumunu sorgulamanız veya sonuçları uzlaştırmanız gerekebilir.

7. Uzun süren web istekleri içinde uyumaktan kaçının

Technical workflow illustration

Örneğimiz, yeniden deneme davranışını kolay anlaşılır kılmak için usleep() kullanır.

Bu, sıkı denetlenen bir yeniden deneme bütçesiyle kısa işlemler için kabul edilebilir olabilir.

Ancak, bir üretim web sitesi, harici bir API'yi beklerken PHP çalışanlarını dakikalarca meşgul etmemelidir.

Bir API'nin şu yanıt verdiğini varsayalım:

HTTP/1.1 429 Too Many Requests
Retry-After: 3600

Bir HTTP isteği içinde bir saat beklemek kötü bir tasarım olurdu.

Daha iyi bir çözüm, işlemi erteler.

Örneğin, bekleyen bir işi depolayın:

Job ID: 1842
Status: pending
Attempts: 2
Next attempt: 2026-11-20 14:30:00 UTC

Zamanlanmış bir çalışan (worker), iş uygun hale geldiğinde bunu işleyebilir.

Bu yaklaşım şunlar için özellikle faydalıdır:

  • Ürün kataloğu senkronizasyonu.
  • E-posta teslimi.
  • Sosyal medya yayını.
  • Belge işleme.
  • Envanter güncellemeleri.
  • Büyük API içe aktarımları.

Ayrıca hataları izlemeyi ve kurtarmayı kolaylaştırır.

8. Yeniden deneme bilgilerini bir veritabanında saklayın

MariaDB tarafından desteklenen bir uygulama için, basit bir iş tablosu şuna benzeyebilir:

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
    )
);

Çalışan (worker), şu koşullarda işleri seçer:

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;

Bu, bir kuyruk uygulamasının yalnızca seçim kısmıdır.

Birden fazla çalışan aynı anda çalışabiliyorsa, işler yinelenen işlemeyi önlemek için uygun bir işlem ve kilitleme stratejisi kullanılarak atomik olarak talep edilmelidir.

Çalışan ayrıca maksimum yeniden deneme sayısını uygulamalı ve kalıcı olarak başarısız olan işleri inceleme gerektiren bir duruma taşımalıdır.

Küçük bir uygulama için, Redis veya özel bir mesaj aracısı tanıtmadan bu veritabanı destekli yaklaşım yeterli olabilir.

9. Hassas verileri ifşa etmeden hataları kaydedin

Faydalı bir API günlüğü dört soruya cevap vermelidir:

  1. Hangi işlem başarısız oldu?
  2. Hangi uzak hizmet beteiligtdi?
  3. HTTP durumu veya taşıma hatası neydi?
  4. Uygulama ne zaman yeniden deneyecek?

Örneğin:

[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 anahtarları, taşıyıcı belirteçleri, tam yetkilendirme başlıkları, parolalar veya gereksiz kişisel bilgileri kaydetmekten kaçının.

İstekleri ilişkilendirmeniz gerekirse, oluşturulmuş bir istek tanımlayıcısı kullanın.

Örneğin:

$requestId = bin2hex(random_bytes(8));

Bu tanımlayıcıyı uygulama günlüklerine ekleyebilir ve desteklendiğinde uzak API'ye gönderebilirsiniz.

10. Yeniden deneme stratejinizi üretimden önce test edin

Yeniden deneme mekanizması, öngörülebilir hata senaryolarına karşı test edilmelidir.

Gerçek bir API kesintisini beklemenize gerek yok.

Yerel bir test uç noktası, belirli durum kodlarını kasıtlı olarak döndürebilir.

Örneğin:

<?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',
]);

Bu uç noktayı yalnızca yerel veya korumalı bir test ortamında çalıştırın.

Sonra istemcinizin şunları yaptığını doğrulayın:

  • HTTP 429'u tespit eder.
  • Retry-After başlığını okur.
  • Yeniden denemeden önce bekler.
  • Yapılandırılan deneme sayısından sonra durur.
  • Gizli bilgileri ifşa etmeden hatayı kaydeder.

HTTP 503 ve kasıtlı olarak yavaş bir uç nokta ile tekrar edin.

Ayrıca, istemcinin kalıcı istek hataları için yeniden denemediğini onaylamak için HTTP 400 yanıtıyla test edin.

Son olarak, bağlantı kesilmeden önce başarılı olabilecek bir işlem test edin. Bu, ödeme ve sipariş entegrasyonları için kritiktir.

11. Güvenilir API entegrasyonları için üretim kontrol listesi

Bir API entegrasyonunu dağıtmadan önce şunları doğrulayın:

Kontrol Beklenen davranış
Bağlantı zaman aşımı Tanımlanmış ve test edilmiş
Genel zaman aşımı Tanımlanmış ve test edilmiş
HTTP 429 Hız sınırlarına saygı gösterir
HTTP 5xx Seçici yeniden deneme
HTTP 4xx Körü körüne yeniden deneme yok
Yeniden deneme sınırı Sonsuz döngüleri engeller
Yeniden deneme gecikmesi Jitter ile geri çekilme
POST işlemleri Etkisizlik veya uzlaştırma
Uzun bekleme süreleri Çalışana (worker) ertelenir
Günlükler Faydalı, özel, temizlenmiş
Çalışan eşzamanlılığı Yinelenen yürütme engellenir
Kalıcı hatalar Görünür ve kurtarılabilir

Sonuç: Güvenilir API'ler kontrol edilmiş hata yönetimi gerektirir

Harici API'ler asla mükemmel şekilde mevcut değildir.

Hatta iyi bakımlı bir hizmet bile geçici aşırı yük, ağ kesintileri veya hız sınırlaması yaşayabilir.

Hedef her hatayı ortadan kaldırmak değil. Hatalar oluştuğunda uygulamanızın öngörülebilir şekilde yanıt vermesini sağlamaktır.

Makul zaman aşımları ve açık HTTP hata işleme ile başlayın. Sınırlı yeniden denemeleri üstel geri çekilmeyle ekleyin, sunucu tarafından sağlanan yeniden deneme gecikmelerine saygı duyun ve yinelenen veriler oluşturabilecek işlemleri otomatik olarak tekrar etmeyin.

Daha karmaşık entegrasyonlar için, yeniden denemeleri web isteklerini açık tutmak yerine kalıcı bir iş kuyruğuna taşıyın.

Bu prensipler, modern bir PHP uygulamasına neredeyse her zaman uygulanır; CMS eklentisi, e-ticaret kataloğu senkronizasyonu, işlem e-postaları gönderme veya ödeme hizmeti entegrasyonu oluşturuyor olun.

Güvenilir bir API istemcisi, sadece bir isteğin nasıl gönderileceğini değil, ne zaman yeniden deneneceğini, ne zaman bekleyeceğini ve ne zaman duracağını bilir.

Resmi referanslar