- Konu sahibi
- #1
API hatası, bir uygulamanın başka bir uygulamadan veri isterken veya veri gönderirken isteğin başarısız olmasıdır. Hatanın nedeni; yanlış URL, eksik kimlik doğrulama bilgisi, hatalı veri biçimi, yetki eksikliği, bulunamayan kaynak, ağ bağlantısı veya API sunucusundaki bir problem olabilir. Hatanın gerçek nedenini anlamak için yalnızca ekrandaki mesajı değil, HTTP durum kodunu ve sunucunun döndürdüğü hata gövdesini birlikte incelemek gerekir.
Bir istemci API'ye istek gönderir. İstek; adres, HTTP yöntemi, başlıklar, kimlik doğrulama bilgileri, sorgu parametreleri ve gerekiyorsa JSON gövdesinden oluşur. API sunucusu bu isteği işler ve bir HTTP durum kodu ile yanıt verir.
Genel olarak
Önemli bir ayrım vardır: Tarayıcıdaki
Bir uygulama
İstemci tarafında temel kontrol şu şekilde yapılabilir:
Bu örnekte başarılı yanıt işlenmeden önce HTTP sonucu kontrol edilir. Böylece hata yanıtı normal ürün verisi gibi kullanılmaz. Bu örnek JSON döndürdüğü belgelenmiş ürün endpoint’i içindir. Başarılı HTTP yanıtı bozuk JSON içerirse ayrıştırma yine hata verir; çağıran kod ağ ve ayrıştırma hatalarını da ele almalıdır. Hata ayrıntıları API dokümantasyonuna göre işlenmelidir.
Aşağıdaki sınıflandırma, ilk teşhisi hızlandırır:
Bu tablo tanı koymak için başlangıç noktasıdır; aynı kod farklı API'lerde farklı hata ayrıntılarıyla dönebilir. Özellikle
En yaygın hata, yalnızca “API çalışmıyor” mesajına bakıp durum kodunu incelememektir. Bir diğer hata,
Token, API anahtarı, parola ve kişisel veriler loglara açık biçimde yazılmamalıdır. Ayrıca sunucudan dönen hata mesajı doğrudan son kullanıcıya gösterilmeden önce temizlenmelidir; teknik ayrıntılar saldırganlara sistem hakkında bilgi verebilir.
Hayır. Ağ kesintisi, süresi dolmuş oturum, yetki kısıtı, API kotası veya karşı sunucudaki geçici arıza da API hatasına neden olabilir.
Geçici sunucu veya ağ hatalarında ve 429 gibi hız sınırı yanıtlarında, API’nin bekleme bilgisi ve tekrar güvenliği dikkate alınarak yapılabilir. Bekleme aralığı ve deneme sınırı belirleyin. Geçersiz JSON, eksik alan veya yetkisiz erişim gibi istemci hatalarında yeniden deneme genellikle sonucu değiştirmez.
HTTP durum kodu, yanıt başlıkları, istek gövdesi, kimlik doğrulama bilgileri, sunucu logları ve varsa istek takip kimliği incelenir.
API hatası nasıl çalışır?
Bir istemci API'ye istek gönderir. İstek; adres, HTTP yöntemi, başlıklar, kimlik doğrulama bilgileri, sorgu parametreleri ve gerekiyorsa JSON gövdesinden oluşur. API sunucusu bu isteği işler ve bir HTTP durum kodu ile yanıt verir.
Genel olarak
2xx kodları başarılı HTTP yanıtını, 4xx kodları istemci kaynaklı problemi, 5xx kodları ise sunucu tarafındaki problemi gösterir. Örneğin 202 Accepted, işlemin kabul edildiğini belirtir; işin tamamlandığını kanıtlamaz. Durum kodu tek başına yeterli değildir; API'nin döndürdüğü message, code veya errors alanları daha ayrıntılı açıklama sağlayabilir.Önemli bir ayrım vardır: Tarayıcıdaki
fetch() çağrısı, sunucu 404 veya 500 döndürdüğünde her zaman JavaScript hatasıyla reddedilmez. Yanıtı aldıktan sonra response.ok veya response.status değerini ayrıca kontrol etmek gerekir.Somut örnek: Ürün bilgisi alınamıyor
Bir uygulama
https://api.example.com/products/42 adresine istek gönderiyor ve 404 alıyorsa ürün gerçekten silinmiş olabilir. Fakat endpoint yolunda yazım hatası, yanlış API sürümü veya 42 değerinin yanlış gönderilmesi de aynı sonucu doğurabilir.İstemci tarafında temel kontrol şu şekilde yapılabilir:
Kod:
async function getProduct() {
const response = await fetch("https://api.example.com/products/42");
if (!response.ok) {
throw new Error("API HTTP hatası: " + response.status);
}
const contentType = response.headers.get("content-type") || "";
if (!contentType.includes("application/json")) {
throw new Error("Beklenen JSON yanıtı alınamadı.");
}
return response.json();
}Bu örnekte başarılı yanıt işlenmeden önce HTTP sonucu kontrol edilir. Böylece hata yanıtı normal ürün verisi gibi kullanılmaz. Bu örnek JSON döndürdüğü belgelenmiş ürün endpoint’i içindir. Başarılı HTTP yanıtı bozuk JSON içerirse ayrıştırma yine hata verir; çağıran kod ağ ve ayrıştırma hatalarını da ele almalıdır. Hata ayrıntıları API dokümantasyonuna göre işlenmelidir.
Yaygın API hata türleri
Aşağıdaki sınıflandırma, ilk teşhisi hızlandırır:
| Durum veya belirti | Muhtemel anlamı | İlk kontrol |
|---|---|---|
| 400 Bad Request | İstek biçimi veya gönderilen veri hatalı | JSON, zorunlu alanlar ve parametreler |
| 401 Unauthorized | Kimlik doğrulama eksik veya geçersiz | Token, API anahtarı ve yetkilendirme başlığı |
| 403 Forbidden | Sunucu isteği anlıyor ancak yerine getirmeyi reddediyor | Kullanıcı rolü, kapsam ve erişim politikası |
| 404 Not Found | Adres veya istenen kaynak bulunamadı | Endpoint yolu, kimlik değeri ve HTTP yöntemi |
| 409 Conflict | İstek mevcut kaynak durumuyla çakışıyor | Aynı kaydın daha önce oluşturulup oluşturulmadığı |
| 429 Too Many Requests | İstek sınırı aşılmış | İstek sıklığı ve varsa bekleme bilgisi |
| 5xx | API sunucusunda beklenmeyen veya geçici sorun | Sunucu logları, tekrar deneme politikası ve servis durumu |
401 ile 403 karıştırılmamalıdır: 401 geçerli kimlik doğrulaması eksikliğine işaret eder. 403 ise erişimin reddedildiğini söyler; kullanıcının mutlaka doğrulandığını kanıtlamaz ve kimlik bilgilerinden bağımsız bir politika nedeniyle de dönebilir.API hatasını çözmek için uygulanacak adımlar
- Tarayıcı geliştirici araçlarında veya istemci loglarında istek URL'sini, HTTP yöntemini, durum kodunu ve yanıt gövdesini kaydedin.
- Endpoint adresini ve HTTP yöntemini dokümantasyonla karşılaştırın.
GET,POST,PUTveDELETEyöntemleri birbirinin yerine kullanılmaz. - Zorunlu başlıkları kontrol edin. JSON gönderiyorsanız genellikle
Content-Type: application/jsonbaşlığı ve geçerli kimlik doğrulama bilgisi gerekir. - Gönderilen JSON verisini doğrulayın. Alan adlarının doğru yazıldığını, zorunlu alanların bulunduğunu ve veri tiplerinin beklendiğini kontrol edin.
- Kimlik doğrulama ile yetkilendirmeyi ayrı inceleyin. Token süresi dolmuşsa yenileyin; kullanıcıda gerekli rol veya kapsam yoksa yetki tanımını düzeltin.
- Hata geçici görünüyorsa yalnızca güvenli ve tekrar edilebilir işlemlerde kontrollü yeniden deneme uygulayın. Her isteği sınırsız biçimde tekrarlamak yükü artırabilir veya aynı kaydı birden fazla oluşturabilir.
- Sorun devam ederse istek zamanı, endpoint, durum kodu, takip kimliği ve hassas bilgiler ayıklanmış hata gövdesiyle API sağlayıcısına başvurun.
Sık yapılan hatalar
En yaygın hata, yalnızca “API çalışmıyor” mesajına bakıp durum kodunu incelememektir. Bir diğer hata,
fetch() çağrısının catch bloğuna düşmesini bekleyerek 404 veya 500 yanıtlarını normal başarı akışı içinde işlemektir.Token, API anahtarı, parola ve kişisel veriler loglara açık biçimde yazılmamalıdır. Ayrıca sunucudan dönen hata mesajı doğrudan son kullanıcıya gösterilmeden önce temizlenmelidir; teknik ayrıntılar saldırganlara sistem hakkında bilgi verebilir.
500 hatasını istemci tarafında rastgele veri değiştirerek çözmeye çalışmak yerine sunucu logları ve istek izleme kayıtları incelenmelidir.Sık sorulan sorular
API hatası her zaman kodlama hatası mıdır?
Hayır. Ağ kesintisi, süresi dolmuş oturum, yetki kısıtı, API kotası veya karşı sunucudaki geçici arıza da API hatasına neden olabilir.
API hatasında yeniden deneme yapılmalı mı?
Geçici sunucu veya ağ hatalarında ve 429 gibi hız sınırı yanıtlarında, API’nin bekleme bilgisi ve tekrar güvenliği dikkate alınarak yapılabilir. Bekleme aralığı ve deneme sınırı belirleyin. Geçersiz JSON, eksik alan veya yetkisiz erişim gibi istemci hatalarında yeniden deneme genellikle sonucu değiştirmez.
Hata mesajı yoksa ne incelenir?
HTTP durum kodu, yanıt başlıkları, istek gövdesi, kimlik doğrulama bilgileri, sunucu logları ve varsa istek takip kimliği incelenir.
