Takip API'si Hata Yönetimi: Geçersiz Takip Numaraları, Hız Sınırları ve Yeniden Denemeler Nasıl Yönetilir

Geçersiz girdileri, geçici hataları, hız sınırlarını ve gönderi durumu sonuçlarını birbirinden ayırarak takip API'si hatalarını yönetin. Geçersiz takip numaralarını değiştirmeden yeniden denemek yerine reddedin veya düzeltin, hız kısıtlaması uygulandığında istek hacmini koordine edin ve geçici hataları sınırlı üstel geri çekilme ve rastgele gecikme ile yeniden deneyin. Bir kayıt veya başka bir yazma isteğini tekrarlamadan önce ilk denemenin başarılı olup olmadığını belirleyin.

Takip verilerini bir sipariş yönetim sistemine, depo platformuna veya müşterilere sunulan bir takip sayfasına bağlayan geliştiriciler için amaç yalnızca daha az başarısız istek değildir. Amaç; yinelenen kayıtlar, yeniden deneme fırtınaları, yanıltıcı teslimat mesajları veya gereksiz destek talepleri olmadan güvenilir gönderi görünürlüğü sağlamaktır.

Bir yanıt seçmeden önce hatayı sınıflandırın

Bir takip entegrasyonunda değerlendirilecek birkaç ayrı sonuç vardır: ağ isteğinin tamamlanıp tamamlanmadığı, API'nin işlemi kabul edip etmediği, istenen her takip öğesinin başarılı olup olmadığı ve gönderi olaylarının mevcut olup olmadığı. Bu dört sonucu tek bir başarı veya başarısızlık bayrağı olarak ele almak önlenebilir hatalara yol açar.

Başarılı bir HTTP yanıtı, bir toplu işlemdeki her öğenin başarılı olduğu anlamına gelmez. Bunun tersine, takip olayı bulunmayan başarıyla işlenmiş bir sorgu da mutlaka API hatası değildir. Yanıt gövdesini inceleyin ve sağlayıcının her sonuç için belgelenmiş anlamını uygulayın.

Koşul	Önerilen işlem	Değiştirmeden yeniden denensin mi?
Biçimi bozuk numara veya geçersiz istek alanı	Girdiyi doğrulayın ve düzeltin	Hayır
Eksik veya geçersiz kimlik bilgileri	Kimlik bilgilerini, izinleri ve ortamı kontrol edin	Düzeltilene kadar hayır
Hız sınırı yanıtı	Etkilenen çalışmayı geciktirin ve ortak istek baskısını azaltın	Gerekli bekleme sonrasında, güvenliyse
Geçici hizmet hatası	Sınırlı geri çekilme uygulayın ve işlemin güvenliğini kontrol edin	Genellikle, yeniden deneme bütçesi dahilinde
Kayıt gönderildikten sonra zaman aşımı	Kaydın mevcut olup olmadığını uzlaştırın	Körü körüne hayır
Gönderi olayı bulunmayan kabul edilmiş sorgu	Belgelenen takip yaşam döngüsünü izleyin	Hızlı yeniden denemeler yerine zamanlanmış yenileme kullanın

HTTP durum kodları bir başlangıç noktası sağlar, ancak sağlayıcıya özgü karar ağacının tamamını oluşturmaz. RFC 9110 HTTP semantiğini, RFC 6585 ise 429 Too Many Requests durumunu tanımlar. Entegrasyonunuz ayrıca belgelenmiş uygulama hata kodlarını ve öğe düzeyindeki sonuçları da yorumlamalıdır.

Geçersiz takip numaraları: hatalı girdiyi eksik olaylardan ayırın

“Geçersiz takip numarası” farklı sorunları ifade edebilir: biçimi bozuk bir tanımlayıcı, desteklenmeyen taşıyıcı-numara birleşimi, gerekli taşıyıcı alanının eksik olması veya sağlayıcıya özgü başka bir doğrulama hatası. Sırf takip olayı döndürülmedi diye bir numaranın geçersiz olduğunu varsaymayın.

Tanımlayıcıya zarar vermeden doğrulayın

• Takip numaralarını dize olarak saklayın. Sayısal depolama, baştaki sıfırları kaldırabilir veya uzun tanımlayıcıları değiştirebilir.
• Orijinal girdiyi koruyun. Dönüşümlerin denetlenebilir kalması için ayrı bir normalleştirilmiş değer tutun.
• İhtiyatlı şekilde normalleştirin. Uygun olduğunda baştaki ve sondaki boşlukları kaldırın; ancak belgelenmiş kurallar izin vermedikçe iç karakterleri kaldırmayın veya harflerin büyük-küçük durumunu değiştirmeyin.
• Gerekli alanları yerel olarak kontrol edin. Boş numaraları, eksik taşıyıcı tanımlayıcılarını ve geçersiz istek yapılarını göndermeden önce yakalayın.
• Evrensel bir takip numarası regex'inden kaçının. Bir taşıyıcı için tasarlanmış bir kural, başka bir taşıyıcının geçerli tanımlayıcılarını reddedebilir.
• Alanın ne içerdiğini doğrulayın. Uç nokta bunları açıkça desteklemediği sürece sipariş numarası, depo referansı ve taşıyıcı takip numarası birbirinin yerine kullanılamaz.

API girdiyi açıkça reddederse otomatik yeniden deneme döngüsüne yönlendirmek yerine düzeltme sürecine aktarın. Her doğrulama sorununu “takip başarısız” olarak ifade etmek yerine “taşıyıcı tanımlayıcısı gerekli” gibi yararlı bir neden ekleyin.

“Olay yok” durumunu ayrı ele alın

Yararlı hareket olayları kullanılabilir hale gelmeden önce bir gönderinin takip tanımlayıcısı olabilir. Doğru yanıt, API'nin belgelenmiş durum modeline ve gönderi bağlamına bağlıdır. Tanımlayıcının gönderim sisteminden gelip gelmediğini, taşıyıcı seçiminin doğru olup olmadığını ve yanıtın reddedilmiş girdi yerine bekleyen veriyi gösterip göstermediğini kontrol edin.

input_rejected, awaiting_events ve temporarily_unavailable gibi farklı dahili durumlar kullanın. Bunlar standartlaştırılmış API değerleri değil, önerilen uygulama durumlarıdır. Geçici bir veri boşluğunun hatalı bir müşteri mesajına dönüşmesini önlemeye yardımcı olurlar.

Hız sınırlarını çalışan başına değil, entegrasyon genelinde yönetin

RFC 6585, HTTP 429'u hız sınırlaması yanıtı olarak tanımlar ve bunun bir Retry-After başlığı içermesine izin verir. Standart, evrensel bir takip API'si kotası veya sayım yöntemi belirlemez. Sınırlar hesap, kimlik bilgisi, uç nokta veya başka bir kapsama göre belgelenebilir; sağlayıcının gerçek kurallarını kullanın.

RFC 9110, Retry-After için iki biçim belirtir: negatif olmayan saniye sayısı veya HTTP tarihi. Her ikisini de ayrıştırın. Değer bir tarihse kalan bekleme süresini dikkatle hesaplayın ve saat farklarını hesaba katın. Değer eksikse veya kullanılamıyorsa yapılandırılmış geri çekilme politikanızdaki varsayılanı uygulayın.

Diğer çalışanlar aynı kotayı kullanmaya devam ederken tek bir çalışanın bağımsız olarak beklemesi yeterli değildir. İlgili kimlik bilgisi veya hesap için hız kontrolünü ortak sınırda uygulayın. Merkezi bir zamanlayıcı, paylaşılan token bucket veya eşdeğer dağıtık bir kontrol bu trafiği koordine edebilir.

1. Etkilenen kapsamı belirleyin. Sınırın hangi uç nokta, kimlik bilgisi veya hesap için geçerli olduğunu belirleyin.
2. Sunucunun bekleme talimatına uyun. Geçerli bir Retry-After değerinin izin verdiğinden daha erken bir yeniden deneme zamanlamayın.
3. Etkilenen kuyruğa alınmış çalışmayı geciktirin. Sınırlar gerçekten bağımsız olduğunda ilgisiz trafiği engellemekten kaçının.
4. Eşzamanlılığı veya istek sıklığını azaltın. İstek düzenini değiştirmeden yalnızca bir kez beklemek aynı sorunu yeniden oluşturabilir.
5. Aralık bırakarak devam edin. Bekleme sona erdiğinde tüm birikmiş işleri aynı anda serbest bırakmayın.

Desteklendiğinde toplu işlemler istek sayısını azaltabilir, ancak belgelenmiş toplu işlem boyutu ve sayım kurallarına uymalıdır. Bir toplu işlemin tek bir kota birimi tükettiğini varsaymayın. Benzer şekilde, gereksiz yoklamayı azaltmak için mevcut olduğunda web kancalarını kullanın; ancak entegrasyonunuzun gerektirdiği uzlaştırma sürecini koruyun.

Geri çekilme ve rastgele gecikme ile sınırlı yeniden denemeler kullanın

Bir hata, isteği değiştirmeden ortadan kalkabilecekse ve işlemi tekrarlamak güvenliyse yeniden denemeler uygundur. Geçici bağlantı hataları ve seçili sunucu hataları bu kategoriye girebilir. Biçimi bozuk bir yük, geçersiz kimlik bilgisi veya kalıcı bir izin sorunu genellikle bunun yerine düzeltme gerektirir.

Uygulanabilir bir varsayılan seçenek, tam rastgele gecikmeli sınırlı üstel geri çekilmedir:

backoff_window = min(max_delay, base_delay * 2^retry_index)
jitter_delay = random(0, backoff_window)
next_delay = max(valid_retry_after_delay, jitter_delay)

Burada retry_index ilk yeniden deneme için sıfırdan başlar ve Retry-After yoksa ek bir minimum bekleme süresi eklenmez. Bunlar zorunlu bir HTTP algoritması değil, uygulama tercihleridir. Temel gecikmeyi, üst sınırı, deneme sayısını ve toplam son tarihi iş yükünüze ve sağlayıcının yönlendirmelerine göre seçin.

Rastgele gecikme, her çalışanın aynı programa göre yeniden deneme yapması yerine istekleri zamana yayar. Gecikme üst sınırı üstel bileşeni sınırlar; daha uzun ve geçerli bir sunucu bekleme talimatını geçersiz kılmamalıdır. Bu bekleme iş son tarihinizi aşarsa erken yeniden denemek yerine politikaya uygun olarak işi erteleyin veya sonlandırın.

Her yeniden deneme zincirine bir son nokta belirleyin

• Deneme sınırı: Ek isteklerin sayısını sınırlayın.
• Geçen süre sınırı: Yararlı işlem penceresini aşmış çalışmayı yeniden denemeyi durdurun.
• Açık sahiplik: Yeniden denemeleri hangi katmanın kontrol edeceğini seçin; böylece HTTP istemcisi yeniden denemeleri ile kuyruk yeniden denemeleri beklenmedik şekilde çoğalmaz.
• Kalıcı zamanlama: Kısa ömürlü işlemler içinde uzun beklemelere güvenmek yerine gecikmiş işleri saklayın.
• Kurtarma yolu: Tükenen işleri, neden ve sonraki işlemle birlikte incelenebilir bir başarısız işler kuyruğuna gönderin.

Süregelen bir kesinti sırasında rutin çağrıları geçici olarak duraklatan ve kontrollü kurtarma yoklamalarına izin veren bir devre kesici kullanmayı değerlendirin. Bu, bir uygulama dayanıklılığı modelidir; belirli bir takip sağlayıcısının bunu gerektirdiğinin kanıtı değildir.

Belirsiz yazma işlemlerini yeniden göndermeden önce çözümleyin

Zaman aşımı, uygulamanızın tam bir yanıt almadığını gösterir. Sunucunun isteği reddettiğini veya hiç işlemediğini kanıtlamaz. Bu ayrım, takip numaraları kaydedilirken veya takip yapılandırması değiştirilirken önemlidir.

RFC 9110, idempotent yöntemleri açıklar ve tekrarın güvenli olduğunu veya ilk işlemin uygulanmadığını bilmek için bir dayanak olmadan idempotent olmayan isteklerin otomatik olarak yeniden denenmesine karşı uyarır. Her takip uç noktasının salt okunur bir sorgu gibi davrandığını varsaymak yerine belgelenmiş işlem semantiğini değerlendirin.

• Mevcut olduğunda sağlayıcının belgelenmiş idempotency mekanizmasını, kapsam ve saklama kurallarına uyarak kullanın.
• Aynı mantıksal işlemin yeniden denemelerinde aynı idempotency anahtarını koruyun; rastgele bir özel başlığın dikkate alınacağını varsaymayın.
• Destekleniyorsa belirsiz bir yazma işlemini tekrarlamadan önce mevcut kaydı kontrol edin.
• Sağlayıcının belgelenmiş gönderi kimliğiyle uyumlu bir yerel benzersizlik kısıtlaması kullanın.
• Kuyruğun yeniden teslim edilmesinin otomatik olarak başka bir yazma işlemini tetiklememesi için işlem sonucunu saklayın.

Toplu işlemler için her öğenin sonucunu kalıcı olarak saklayın. Yalnızca geçici olarak başarısız olarak sınıflandırılan öğeleri yeniden deneyin ve sonucu bilinmeyen öğeleri uzlaştırın. Toplu işlemin tamamını yeniden oynatmak başarılı işleri tekrarlayabilir ve istek kotasını gereksiz yere tüketebilir.

Politikayı takip sağlayıcınıza uygulayın

Bir 17TRACK entegrasyonu için sağlayıcıya özgü sözleşmenin başlangıç noktaları olarak Tracking API page ve official API documentation sayfalarını kullanın. Hata sınıflandırıcınızı yapılandırılabilir tutun ve genel bir HTTP kılavuzundaki varsayımları sabit kodlamayın.

Uygulamadan önce ilgili uç noktanın istek şemasını, yanıt zarfını, öğe düzeyindeki hata anlamlarını, hız sınırı kapsamını, toplu işlem kısıtlamalarını ve yinelenen gönderim kurallarını doğrulayın. Olay teslimini kullandığınızda ayrıca onay, kimlik doğrulama ve yeniden teslim gereksinimlerini de doğrulayın. Bu kılavuz sayısal bir 17TRACK hız sınırı, yeniden deneme zamanlaması veya idempotency özelliği öngörmez.

Doğrulanan her kuralı sağlayıcı yanıtından uygulama işlemine giden bir eşlemede kaydedin: girdiyi düzelt, yapılandırmayı onar, bekle, uzlaştır veya üst makama ilet. Tanınmayan bir hata tanılama bağlamını korumalı ve sınırsız yeniden denemelere varsayılan olarak yönelmek yerine sınırlı bir geri dönüş yolunu izlemelidir.

Kurtarma kalitesini izleyin ve hata yollarını test edin

İşlemi, uç noktayı, HTTP durumunu, uygulama hata kodunu, deneme numarasını, gecikmeyi, bir sonraki zamanlanmış işlemi ve sağlandığında sağlayıcı istek tanımlayıcısını günlüğe kaydedin. API anahtarlarını, gereksiz adres bilgilerini veya sınırsız yanıt gövdelerini kaydetmekten kaçının. Tam değerlerin gerekli olmadığı durumlarda takip tanımlayıcılarını maskeleyin veya özetleyin.

Geçersiz girdi oranlarını, hız kısıtlamasını, kuyruk yaşını, tükenen yeniden denemeleri ve son başarılı eşitlemeyi ayrı ayrı izleyin. Bir entegrasyonun HTTP hata oranı düşükken gönderi bilgileri yine de güncelliğini yitirmiş olabilir. Müşterilere sunulan sayfalar bilinen son gönderi durumunu korumalı ve yenileme hatasını taşıyıcı tarafından bildirilen teslimat istisnasından ayırmalıdır.

Yayından önce biçimi bozuk girdileri, olayı olmayan geçerli tanımlayıcıları, Retry-After başlığının her iki biçimini, eksik başlıkları, kısmi toplu işlem hatalarını, yazma işlemlerinden sonraki zaman aşımlarını ve kuyruğun yeniden teslim edilmesini test edin. Ayrıca yeniden deneme bütçesini tüketecek kadar uzun bir kesintiyi simüle edin. Test yalnızca işler öngörülebilir şekilde durduğunda veya ertelendiğinde, başarılı öğeler gereksiz yere yeniden oynatılmadığında ve başarısız öğeler kurtarılabilir kaldığında başarılı sayılır.

SSS

Geçersiz bir takip numarası otomatik olarak yeniden denenmeli mi?

API girdiyi geçersiz olarak açıkça reddettiğinde hayır. Önce numarayı, taşıyıcı seçimini veya gerekli alanları düzeltin. Yanıt bunun yerine gönderi olaylarının henüz kullanılamadığını ifade ediyorsa bunu doğrulama hatası olarak ele almak yerine belgelenmiş yenileme iş akışını kullanın.

HTTP 200, toplu bir isteğin tamamen başarılı olduğu anlamına gelir mi?

Her zaman değil. İşlem düzeyindeki ve öğe düzeyindeki sonuçlar için sağlayıcının yanıt şemasını kontrol edin. Başarılı sonuçları kalıcı olarak saklayın ve bir öğeyi yeniden denemenin geri kalanını gereksiz yere tekrarlamaması için hataları ayırın.

Bir takip entegrasyonu kaç yeniden denemeye izin vermeli?

Evrensel bir sayı yoktur. Deneme sınırını ve geçen süre bütçesini sağlayıcının yönlendirmelerine, işlemin güvenliğine ve sonucun ne kadar süre yararlı kaldığına göre belirleyin. Zamanlanmış bir arka plan eşitlemesi, etkileşimli bir müşteri isteğinden farklı bir kurtarma penceresini tolere edebilir.

Zaman aşımı, bir gönderiyi hemen başarısız olarak işaretlemeli mi?

Hayır. İstek zaman aşımı bir entegrasyon sonucudur, gönderi olayı değildir. Bilinen son takip durumunu koruyun, güvenli kurtarmayı zamanlayın ve bağlantı sorununu teslimat başarısızlığı bildirimine dönüştürmekten kaçının.

Yeniden denemeler tükendiğinde ne olmalı?

İşi tanılama bağlamıyla birlikte kalıcı bir başarısız işler veya inceleme kuyruğuna taşıyın. Kurtarma için düzeltilmiş girdi, yenilenmiş kimlik bilgileri, sağlayıcı desteği veya daha sonra kontrollü bir yeniden oynatma gerekip gerekmediğini belirleyin. İşi sessizce silmeyin veya aynı sınırsız yeniden deneme döngüsünü başlatmayın.

Kaynaklar

• RFC 9110: HTTP Semantics — HTTP durum semantiği, idempotent yöntemler, otomatik yeniden deneme değerlendirmeleri ve Retry-After alanı.
• RFC 6585: Additional HTTP Status Codes — 429 Too Many Requests tanımı ve isteğe bağlı Retry-After başlığı.
• 17TRACK Tracking API — takip API'si ürünü için resmi başlangıç noktası.
• 17TRACK API documentation — sağlayıcıya özgü entegrasyon gereksinimlerini kontrol etmek için referans.