API Timeout Hatası: Nedenleri ve Adım Adım Çözümü

API timeout hatası, istemcinin bağlantıyı kurmak veya karşı taraftan beklenen yanıtı almak için tanınan süre içinde ilerleme görememesi anlamına gelir. Bu hata tek başına sunucunun bozuk olduğunu göstermez; sorun DNS çözümlemesinde, ağ bağlantısında, sunucunun isteği işlemesinde, veri aktarımında ya da istemci yapılandırmasında ortaya çıkabilir.

İlk teşhis sorunuz şu olmalı: Hata bağlantı kurulmadan önce mi, yoksa bağlantı kurulduktan sonra yanıt beklerken mi oluşuyor? Python Requests belgelerinde bağlantı kurma süresi ile yanıt bekleme süresi ayrı değerlendirilebilir; ayrıca timeout açıkça verilmezse istemci süresiz bekleyebilir. Requests Quickstart dokümantasyonu bu davranışı ve timeout istisnalarını açıklar.

API timeout hatası ne anlama gelir?

İstemci-sunucu iletişimi basitçe şu akışla düşünülebilir:

1. İstemci, API adresinin hangi sunucuya karşılık geldiğini bulur.
2. Sunucuya ağ bağlantısı kurulur.
3. İstemci HTTP isteğini gönderir.
4. Sunucu isteği işler ve yanıt başlıklarını, ardından yanıt gövdesini gönderir.
5. İstemci yanıtı alıp uygulamanın kullanacağı veriye dönüştürür.

Bu adımlardan birinde belirlenen süre boyunca ilerleme olmazsa timeout oluşabilir. Örneğin sunucunun adresi çözümlenemiyorsa veya sunucuya bağlantı kurulamıyorsa sorun connect timeout tarafında aranır. Bağlantı kurulmuş, istek gönderilmiş ancak sunucu uzun süre veri göndermemişse bu kez read timeout söz konusu olabilir.

Python Requests içinde requests.exceptions.ConnectTimeout, bağlantı kurulurken zaman aşımını; requests.exceptions.ReadTimeout ise sunucudan veri beklenirken zaman aşımını ifade eder. Her ikisi de daha genel olan requests.exceptions.Timeout ile yakalanabilir. Bu ayrım, timeout süresini rastgele yükseltmek yerine hangi aşamanın yavaşladığını anlamaya yardım eder.

Bu nedenle timeout ile HTTP durum kodunu aynı şey gibi değerlendirmemek gerekir. HTTP 500 yanıtında sunucudan bir HTTP yanıtı alınmıştır; timeout durumunda ise istemci, beklediği aşamada gerekli ilerlemeyi görememiş olabilir.

Timeout oluşabilecek katmanlar: Sorun nerede takılıyor?

DNS çözümleme: Alan adı IP adresine dönüşüyor mu?

İstek daha sunucuya ulaşmadan önce alan adının bir IP adresine çevrilmesi gerekir. Alan adı çözümlenmiyorsa yanlış yazılmış URL, geçici DNS sorunu, kurum ağı veya yerel DNS yapılandırması incelenmelidir. Komut satırında nslookup ya da dig ile alan adının çözümlenip çözümlenmediğini kontrol edebilirsiniz. Sonuç alınamıyorsa uygulama kodunu değiştirmeden önce DNS katmanını elemek gerekir.

TCP bağlantısı: Hedefe ağ üzerinden ulaşılabiliyor mu?

DNS çalışsa bile hedef sunucunun ilgili portuna bağlantı kurulamayabilir. Güvenlik duvarı, VPN, kapalı port, ağ yönlendirmesi veya proxy bu aşamayı etkileyebilir. Aynı hedefi tarayıcıdan açmak tek başına yeterli kanıt değildir; tarayıcı farklı proxy, önbellek veya bağlantı ayarları kullanabilir. Kontrollü bir ortamda curl -v gibi bir araçla bağlantının hangi aşamada kaldığını gözlemlemek daha açıklayıcıdır.

Sunucunun isteği işleme süresi

Bağlantı kurulup istek gönderildikten sonra sunucu veritabanı sorgusu, dış servis çağrısı veya yoğun bir hesaplama yapıyor olabilir. Bunu anlamak için aynı API’nin küçük ve güvenli bir sağlık endpoint’iyle karşılaştırma yapın. Sağlık endpoint’i hızlı, asıl işlem endpoint’i yavaşsa ağdan çok sunucu tarafındaki işlem süresi araştırılmalıdır.

Yanıt başlıkları ile yanıt gövdesini ayırın

Sunucu yanıt başlıklarını göndermiş olabilir; ancak büyük yanıt gövdesi yavaş geliyor olabilir. Bu durumda “sunucu hiç yanıt vermedi” demek yanıltıcıdır. İstemcinin yanıt başlıklarını ne zaman aldığını ve gövdeyi okumaya ne zaman başladığını ayrı ayrı ölçmek, sorunun veri aktarımında mı yoksa sunucunun ilk yanıtında mı olduğunu gösterir.

Proxy, güvenlik duvarı ve istemci ayarları

Requests, ortam değişkenlerindeki HTTP_PROXY, HTTPS_PROXY, ALL_PROXY ve NO_PROXY değerlerinden etkilenebilir; kurumsal ağlarda istek doğrudan API’ye değil, önce proxy’ye gidebilir. Requests Advanced Usage dokümantasyonu, proxy ortam ayarlarını ve connect/read timeout ayrımını açıklar. Bu yüzden farklı bilgisayarlarda aynı kodun farklı davranması mümkündür.

Son olarak, kütüphanelerin varsayılan timeout davranışlarını her ortamda aynı kabul etmeyin. İstemci kodunda timeout değerini açıkça belirtin, kullanılan proxy ayarlarını inceleyin ve işletim sistemi ya da kurum ağı tarafından uygulanan ek zaman aşımı sınırlarını kontrol edin.

API timeout teşhisinde izlenecek doğru sıra

API timeout hatasını çözmenin en hızlı yolu, timeout süresini hemen artırmak değil, isteğin hangi aşamada durduğunu daraltmaktır. Karar akışı şu sırayla ilerler: DNS çözümleme → bağlantı kurulması → sunucunun yanıt üretmesi → veri aktarımı → istemci ayarları.

1. Hata türünü ve traceback bilgisini okuyun. Gözlenebilir sinyal, hatanın ConnectTimeout, ReadTimeout, ConnectionError veya bir HTTP durum kodu olarak görünmesidir. Önce traceback’in son satırını ve istek URL’sini inceleyin. Hata timeout değilse, timeout çözümü uygulamadan ilgili hata sınıfına geçin.
2. DNS çözümlemesini kontrol edin. Alan adı IP adresine çevrilemiyorsa istek sunucuya ulaşamaz. Aynı alan adını başka bir istemciyle veya DNS çözümleme testiyle kontrol edin. Alan adı çözümleniyorsa bağlantı aşamasına; çözümlenmiyorsa DNS, yerel ağ veya DNS yapılandırmasına odaklanın.
3. TCP bağlantısının kurulup kurulmadığını ayırın. ConnectTimeout genellikle istemcinin hedefe bağlantı kurma aşamasını tamamlayamadığını gösterir. Port, ağ erişimi, güvenlik duvarı ve proxy yolunu kontrol edin. Bağlantı kurulabiliyorsa sunucunun yanıt üretme aşamasını inceleyin.
4. Sunucunun yanıt üretmesini bekleme aşamasını inceleyin. Bağlantı kurulmuş fakat ilk yanıt verisi gelmemişse yavaş bir sorgu, yoğun sunucu veya uygulama içi işlem söz konusu olabilir. Aynı endpoint’i düşük maliyetli bir istekle karşılaştırın. Yalnızca ağır istekte gecikme varsa istemci timeout’unu değil, sunucu işleminin kapsamını araştırın.
5. Yanıt verisinin indirilmesinde gecikme olup olmadığını kontrol edin. İlk veri geldikten sonra aktarım duruyorsa büyük yanıt, yavaş bağlantı veya akışın kesilmesi ihtimali vardır. Küçük bir yanıtla test yapın ve yanıt boyutunu karşılaştırın. Sorun yalnız büyük yanıtta görülüyorsa veri aktarımı ve yanıt biçimine odaklanın.
6. Proxy, güvenlik duvarı ve istemci timeout ayarlarını doğrulayın. Aynı kodun farklı ağda çalışıp çalışmadığını karşılaştırın. Ortam değişkenleriyle tanımlanan proxy ayarlarını, TLS yapılandırmasını ve timeout değerinin gerçekten isteğe aktarıldığını kontrol edin. Ayarlar doğruysa kontrollü tekrar denemesine geçin.
7. Güvenli ve sınırlı bir tekrar denemeyle sonucu karşılaştırın. Aynı isteği kısa bir beklemeyle en fazla birkaç kontrollü denemede gözlemleyin. GET gibi tekrar edilmesi genellikle daha düşük riskli isteklerde karşılaştırma yapılabilir; sipariş oluşturma veya ödeme gibi veri değiştiren isteklerde yeniden gönderim yinelenen işlem oluşturabilir.

Python requests ile connect ve read timeout ayarlama

Python’da bağlantı kurma süresi ile sunucudan veri bekleme süresini ayrı ayarlamak için timeout=(connect_timeout, read_timeout) biçimi kullanılır. birebir Python dersleri kapsamında bu ayrımı traceback okuyarak uygulamak, hatayı tek bir “API çalışmıyor” başlığı altında toplamaktan daha sağlıklı bir yöntemdir.

import requests

try:
    response = requests.get("https://example.com", timeout=(3, 10))
    response.raise_for_status()
    print("Başarılı yanıt:", response.status_code)
except requests.exceptions.ConnectTimeout:
    print("Bağlantı kurulurken zaman aşımı oluştu.")
except requests.exceptions.ReadTimeout:
    print("Sunucudan veri beklerken zaman aşımı oluştu.")
except requests.exceptions.RequestException as error:
    print("İstek hatası:", error)

Bağlantı kurulamazsa ConnectTimeout, bağlantı kurulup sunucudan veri bekleme süresi aşılırsa ReadTimeout dalı çalışır. Requests’in resmî belgelerinde tuple timeout kullanımı ve bu iki istisnanın ayrımı açıklanır; Requests timeout dokümantasyonu üzerinden ayrıntıları inceleyebilirsiniz.

Timeout Süresini Artırmak ve Retry Uygulamak Ne Zaman Doğrudur?

API timeout hatası aldığınızda ilk refleks timeout süresini büyütmek olabilir. Ancak bu ayar, DNS çözümleme sorununu, hedef sunucuya erişememeyi, sunucunun isteği geç işlemesini veya yanıtın aktarım sırasında yavaşlamasını kendiliğinden düzeltmez. Sadece hatanın ortaya çıkması için daha uzun süre beklemenize neden olabilir. Bu nedenle timeout değerini artırmadan önce problemin hangi aşamada oluştuğunu belirlemek gerekir.

HTTP yanıtı alabiliyorsanız yaşadığınız durum timeout değil, çoğu zaman bir HTTP durum kodudur. RFC 9110 HTTP Semantics içinde durum kodları; istemci hataları, sunucu hataları ve başarılı yanıtlar gibi sınıflara ayrılır. Timeout'ta ise istemci, belirlenen süre içinde beklediği bağlantıyı veya veriyi tamamlayamamış olabilir.

Retry, hatayı düzeltmek değil yeniden denemek demektir. Bu nedenle yalnızca geçici olma ihtimali yüksek hatalarda ve isteğin tekrarlanması güvenliyse kullanılmalıdır. Örneğin bir kaynağı okumak için yapılan GET isteği, sunucu ilk denemede yanıt veremediğinde sınırlı sayıda yeniden denenebilir. Her deneme arasında artan bekleme kullanmak, aynı anda çok sayıda istemcinin sunucuyu tekrar tekrar zorlamasını azaltır.

Retry kararı verirken şu çerçeveyi kullanın:

1. İsteğin veri değiştirip değiştirmediğini belirleyin.
2. Hatanın geçici ağ sorunu mu, yetki veya endpoint hatası mı olduğunu ayırın.
3. Retry sayısını düşük ve belirli bir üst sınırla tanımlayın.
4. Denemeler arasına artan bekleme süresi ekleyin.
5. İsteklerin toplamda ne kadar süre bekleyebileceğini ayrıca sınırlayın.
6. Her denemeyi hassas verileri loglamadan kaydedin.

Ödeme başlatma, kayıt oluşturma, sipariş gönderme, dosya yükleme veya silme gibi işlemlerde körlemesine retry tehlikelidir. İstemci timeout aldıktan sonra sunucu işlemi aslında tamamlamış olabilir; istemci bunu öğrenemediği için aynı isteği yeniden gönderirse işlem iki kez gerçekleşebilir. Bu senaryolarda sunucunun desteklediği idempotency anahtarı veya güvenli tekrar mekanizması kullanılmalıdır. Böylece sunucu aynı işlem kimliğini taşıyan tekrar isteği yeni bir işlem olarak değil, önceki işlemin devamı veya sonucu olarak değerlendirebilir.

Timeout değerini değiştirmek gerekiyorsa bunu ölçüm sonucuna dayandırın. Örneğin sunucu büyük bir rapor üretirken yanıt süresi doğal olarak uzuyorsa read timeout için uygun bir bütçe belirlenebilir. Fakat DNS çözümlemesi başarısızsa read timeout'u artırmak, bağlantı kurulmadığı için fayda sağlamaz. Aynı şekilde sürekli 401, 403 veya 404 alan bir isteğe retry eklemek de kimlik doğrulama, yetki veya URL sorununu çözmez.

Uygulanabilir Son Kontrol Listesi ve Öğrenmeyi Pekiştirme

API timeout sorununu çözmenin en güvenli yolu, önce hata sınıfını ayırmaktır. Ardından DNS çözümlemesini, hedefe ağ bağlantısını, sunucunun isteği işleme süresini, yanıtın aktarımını ve istemci ayarlarını sırayla kontrol edin. Bu aşamalardan sonra gerekiyorsa sınırlı retry veya timeout ayarı değişikliği uygulayın.

• Endpoint adresini ve kullanılan HTTP yöntemini (GET, POST, PUT, PATCH veya DELETE) doğrulayın.
• Hatanın ne zaman oluştuğunu not edin: bağlantı kurulurken mi, yanıt beklenirken mi, veri aktarılırken mi?
• Connect timeout ile read timeout ayrımını inceleyin.
• Alan adının DNS üzerinden doğru IP adresine çözümlenip çözümlenmediğini kontrol edin.
• Proxy, VPN, güvenlik duvarı ve kurumsal ağ kurallarını gözden geçirin.
• Yanıt kodu varsa bunu timeout istisnasından ayrı değerlendirin.
• Retry kullanacaksanız işlemin güvenli şekilde tekrarlanabildiğinden, deneme sayısının ve toplam süre bütçesinin sınırlı olduğundan emin olun.
• Loglarda token, parola, kişisel veri ve ödeme bilgisini açık biçimde saklamayın.

API ve temel programlama kavramlarınızı kendi seviyenizle karşılaştırarak pekiştirmek için ücretsiz yazılım bilgi testi üzerinden mevcut durumunuzu ölçebilir, ardından konuyu uygulamalı sürdürmek için video eğitim seçeneklerini inceleyebilirsiniz.

Sık Sorulan Sorular

API timeout hatası ile HTTP 500 hatası arasındaki temel fark nedir?

Timeout, istemcinin belirlenen sürede bağlantıyı veya yanıtı tamamlayamaması anlamına gelir. HTTP 500 ise sunucunun isteği alıp işlerken beklenmeyen bir sunucu hatasıyla karşılaştığını gösteren bir yanıttır. Yani timeout'ta yanıt hiç alınamamış olabilir; 500 hatasında ise HTTP yanıtı alınmıştır.

ConnectTimeout ve ReadTimeout hangi durumlarda oluşur?

ConnectTimeout, istemcinin DNS çözümlemesinden sonra hedef sunucuya bağlantı kuramaması veya bağlantı kurma aşamasının zaman sınırını aşmasıyla oluşur. ReadTimeout ise bağlantı kurulmasına rağmen sunucunun yanıtını beklenen sürede gönderememesi ya da yanıt aktarımının tamamlanamaması durumunda görülür.

Timeout süresini artırmak sorunu gerçekten çözer mi?

Bazen sunucunun geçerli bir işlem için daha uzun süreye ihtiyaç duyduğu durumlarda yardımcı olabilir. Ancak DNS, proxy, ağ erişimi, yanlış endpoint veya yetki sorunlarını çözmez. Önce timeout'un hangi aşamada oluştuğu belirlenmeli, ardından ölçüme dayalı bir süre değişikliği yapılmalıdır.

API isteklerinde retry kullanmak hangi durumlarda risklidir?

Retry; ödeme, kayıt oluşturma, silme veya başka veri değiştiren işlemlerde risklidir. İlk istek sunucuda tamamlanmış, fakat yanıt istemciye ulaşmamış olabilir. İstemci yeniden denediğinde aynı işlem iki kez gerçekleşebilir. Bu nedenle idempotency anahtarı, sunucu destekli güvenli tekrar mekanizması ve sınırlı deneme sayısı kullanılmalıdır.

DNS çözümlemesinin timeout sorununa neden olduğunu nasıl anlayabilirim?

Alan adının IP adresine çözümlenip çözümlenmediğini ve farklı DNS sunucularında aynı sonucun alınıp alınmadığını kontrol edin. DNS sorgusu tamamlanmadan bağlantı kurulamadığı için sorun bağlantı aşamasında görünür. Bu durumda read timeout'u artırmak yerine DNS yapılandırması, yerel ağ, VPN ve proxy ayarları incelenmelidir.

Bir timeout hatasında amaç en uzun süre beklemek değil, isteğin hangi aşamada durduğunu kanıtlarla bulmaktır. Katmanları sırayla kontrol ettiğinizde hem gereksiz retry kullanımını hem de veri kaybı riskini azaltabilirsiniz.