Tracking API Kimlik Doğrulama Hatası: 401/403 Yanıtlarının 7 Nedeni ve Nasıl Düzeltilir
Bir tracking API kimlik doğrulama hatası genellikle yedi nedenden birinden kaynaklanır: eksik kimlik bilgisi, yanlış biçimlendirilmiş kimlik doğrulama başlığı, geçersiz veya iptal edilmiş gizli anahtar, ortam uyumsuzluğu, yetersiz izinler, süresi dolmuş belirteç veya geçersiz imza ya da isteği engelleyen bir güvenlik kuralı. 401 veya 403 yanıtını düzeltmek için önce yanıtı hangi sistemin döndürdüğünü belirleyin, ardından isteği sağlayıcının kimlik doğrulama gereksinimlerine göre kontrol edin. Değiştirilmemiş kimlik bilgileriyle tekrarlanan denemeler, temel sorunu nadiren çözer.

Bu kılavuz, gönderi takibini bir e-ticaret platformuna, sipariş yönetim sistemine, depo uygulamasına veya dahili gösterge paneline bağlayan geliştiriciler ve entegrasyon ekipleri içindir. Entegrasyonun tamamında kimlik bilgilerini değiştirmek yerine tek bir başarısız istekle başlayın.
Önce 401 ile 403 arasındaki farkı belirleyin
HTTP tanımları tam bir teşhis değil, bir başlangıç noktası sağlar. 401 Unauthorized, isteğin hedef kaynak için geçerli kimlik doğrulama bilgilerini içermediği anlamına gelir. 403 Forbidden, sunucunun isteği anladığı ancak yerine getirmeyi reddettiği anlamına gelir. 403 yanıtı, kimlik doğrulamanın başarılı olduğunu mutlaka kanıtlamaz: bir ağ geçidi veya güvenlik hizmeti, uygulama kimlik bilgilerini değerlendirmeden önce isteği reddedebilir.
RFC 9110 uyarınca 401 yanıtı oluşturan bir sunucu, WWW-Authenticate sorgulamasını içermelidir. Mevcutsa bu başlığı inceleyin; ancak yanıt gövdesini ve sağlayıcının hata belgelerini de okuyun. Uygulamalar hataları her zaman aynı şekilde göstermez.
| Gözlemlediğiniz durum | Öncelikle araştırılacak konu |
|---|---|
| Eksik veya geçersiz kimlik bilgisi mesajıyla birlikte 401 | Kimlik bilgisi ekleme, başlık biçimi ve kimlik bilgisinin geçerliliği |
| Yetersiz izin mesajıyla birlikte 403 | Kapsamlar, hesap erişimi, kiracı ve kaynak sahipliği |
| HTML güvenlik sayfasıyla birlikte 403 | Ağ geçidi, proxy, güvenlik duvarı veya erişim politikası |
| JSON içinde hatayla birlikte HTTP başarısı | Sağlayıcının uygulama düzeyindeki hata alanları |
Günlüklerinizde aktarım durumunu ve uygulama durumunu ayrı tutun. code adlı bir JSON alanı otomatik olarak HTTP durumu değildir ve başarılı bir HTTP alışverişi, istenen takip işleminin başarılı olduğu anlamına gelmez.
Güvenli bir tanılama kaydı alın
Herhangi bir şeyi değiştirmeden önce UTC zaman damgasını, HTTP yöntemini, ana makine adını, yolu, yanıt durumunu, sağlayıcı hata mesajını, istek kimliğini ve dağıtım ortamını kaydedin. Yanıtın tracking sağlayıcısından, kendi arka ucunuzdan veya bir aracıdan gelip gelmediğini belirtin.
Kimlik doğrulama başlığı adlarını ve değerlerin mevcut olup olmadığını kaydedin; ancak tam API anahtarlarını, bearer token'larını, yenileme token'larını veya imzalama gizli anahtarlarını asla günlüğe kaydetmeyin. Maskelenmemiş istek izlerini dışa aktarmaktan kaçının. Takip numaraları ve gönderi ayrıntıları da kuruluşunuzun veri işleme kuralları kapsamında maskelenmeyi gerektirebilir.
Sorunu yeniden oluşturmak için sağlayıcı tarafından belgelenmiş, düşük etkili bir işlem kullanın. Kimlik doğrulamayı test etmek amacıyla gönderileri tekrar tekrar kaydetmeyin, abonelikler oluşturmayın veya webhook ayarlarını değiştirmeyin.
Tracking API 401/403 yanıtlarının 7 nedeni
1. Kimlik bilgisi API'ye hiç ulaşmıyor
Bir gizli anahtar dağıtım konsolunda mevcut olabilir, ancak çalışan uygulamanın kullanımına sunulmamış olabilir. Yaygın hata noktaları arasında eksik bir ortam değişkeni, yanlış bir gizli anahtar başvurusu, yapılandırma değişikliğinden sonra yeniden başlatılmamış bir worker veya boş değerleri atlayan bir istek oluşturucu bulunur.
Bir proxy de kimlik doğrulama başlığını kaldırabilir. Yönlendirmeler de önemlidir; çünkü bir HTTP istemcisi hassas başlıkları farklı bir ana makineye iletmeyebilir.
- Kontrol: İsteği güvenilen son dışa giden noktada inceleyin. Gerekli başlığın mevcut olduğunu ve boş olmayan bir değer içerdiğini doğrulayın.
- Düzeltme: Gizli anahtar eşlemesini veya istek oluşturmayı düzeltin, ardından gerekirse etkilenen işlemi yeniden yükleyin.
- Doğrulama: Aynı işlemi yalnızca bir geliştiricinin dizüstü bilgisayarından değil, dağıtılmış uygulama üzerinden çalıştırın.
Yerel istekler çalışıyor ancak arka plan işleri başarısız oluyorsa önce çalışma zamanı yapılandırmalarını karşılaştırın. Uygulama ve iş worker'ları gizli anahtarları farklı mekanizmalarla alabilir.
2. Kimlik doğrulama biçimi yanlış
Tracking API'lerinin tümü aynı kimlik doğrulama şemasını kabul etmez. Bir sağlayıcı özel bir API anahtarı başlığı, OAuth bearer token'ı veya imzalı istek gerektirebilir. Geçerli bir anahtarı Authorization: Bearer içine koymak, uç nokta farklı bir başlık bekliyorsa işe yaramaz.
Diğer hatalar arasında gizli anahtara tırnak işaretlerini kopyalamak, sağlayıcının gerektirmediği bir ön ek eklemek, yinelenen kimlik doğrulama başlıkları göndermek veya farklı bir kimlik doğrulama yöntemine uygulanan bir SDK yapılandırma alanını kullanmak bulunur.
- Kontrol: Gerçek isteği, tam uç nokta ve API sürümü için resmi örnekle karşılaştırın.
- Düzeltme: Belgelenen başlık adı, değer biçimi ve kimlik doğrulama şemasıyla eşleşin. Geçici çözüm olarak gizli anahtarı URL'ye taşımayın.
- Doğrulama: Kimlik bilgilerini maskeleyerek basit bir isteği SDK tarafından oluşturulan istekle karşılaştırın.
HTTP semantiği kapsamında HTTP başlık alanı adları büyük/küçük harfe duyarlı değildir. Bu nedenle yalnızca büyük/küçük harf kullanımını değiştirmek normal çözüm değildir. Doğru alana, değere ve iletim yoluna odaklanın.
3. Anahtar yanlış, iptal edilmiş veya artık tutarlı biçimde dağıtılmıyor
Kopyalanan bir anahtar eksik olabilir, başka bir hesaba ait olabilir veya bir güvenlik değişikliği sırasında iptal edilmiş olabilir. Kimlik bilgisi döndürme işlemi de aralıklı hatalara yol açabilir: bazı uygulama örnekleri yeni gizli anahtarı kullanırken diğerleri eski anahtarı kullanmaya devam edebilir.
Her API anahtarının otomatik olarak süresinin dolduğunu varsaymayın. Süre dolumu ve döndürme kuralları sağlayıcıya ve kimlik bilgisi türüne bağlıdır.
- Kontrol: Yetkili hesap konsolunda kimlik bilgisi durumunu doğrulayın ve uygulamalar, worker'lar ve zamanlanmış işler arasındaki dağıtılmış gizli anahtar sürümünü karşılaştırın.
- Düzeltme: Gizli anahtar yönetimi süreciniz üzerinden geçerli bir kimlik bilgisi dağıtın. Açığa çıkma şüphesi varsa olay prosedürünüzü izleyin ve güvenliği tehlikeye giren kimlik bilgisini iptal edin.
- Doğrulama: Dağıtımdan sonra etkilenen her yürütme yolunu kontrol edin. Tek bir başarılı istek, her örneğin güncellendiğini kanıtlamaz.
Desteklendiği yerlerde dağıtımları ayırt etmek için gizli olmayan bir kimlik bilgisi tanımlayıcısı veya secret-manager sürümü kullanın. Bir müşteriden veya iş arkadaşınızdan tam anahtarı destek talebine yapıştırmasını asla istemeyin.
4. Kimlik bilgisi ve uç nokta farklı ortamlara ait
Bazı hizmetler üretim ve test kimlik bilgilerini, bölgesel uç noktaları, hesapları veya kiracıları birbirinden ayırır. Geçerli bir kimlik bilgisi yanlış ana makineye veya hesap bağlamına gönderildiğinde başarısız olabilir. Bu kontrol yalnızca sağlayıcı bu ayrımları belgeliyorsa geçerlidir.
Başka bir olasılık da güncel olmayan temel URL'dir. Bir entegrasyon eski bir uç noktayı kullanırken kimlik doğrulama yapılandırması daha yeni bir API için güncellenmiş olabilir.
- Kontrol: Şema, ana makine adı, API sürümü, yol ve gerekli hesap veya kiracı tanımlayıcısı dahil olmak üzere hedefin tamamını inceleyin.
- Düzeltme: Kimlik bilgisini amaçlanan ortam ve uç noktayla eşleştirin. Her ortamın URL ve gizli anahtar yapılandırmasını birlikte tutun.
- Doğrulama: Çalışan dağıtımda çözümlenen hedefi doğrulayın ve istemcinin yönlendirmeleri izleyip izlemediğini kontrol edin.
Gerçek bir kimlik bilgisiyle tahmini ana makinelerin listesini denemekten kaçının. Yalnızca sağlayıcı tarafından belgelenen uç noktaları kullanın.
5. Kimlik doğrulama başarılı, ancak izin yetersiz
Bir kimlik bilgisi çağrıyı yapan kişiyi tanımlayabilir ancak istenen işleme yetki vermeyebilir. Gönderi olaylarını okumak, takip numaralarını kaydetmek, abonelikleri değiştirmek ve hesabı yönetmek farklı erişim hakları gerektirebilir.
Kaynak sahipliği de önemlidir. Bir çalışma alanında görünen bir gönderiye, başka bir çalışma alanıyla ilişkilendirilmiş kimlik bilgisi üzerinden erişilemeyebilir. Bazı sistemler hata ayrıntılarını kasıtlı olarak sınırlar; bu nedenle tek başına 403, bir kaynağın mevcut olup olmadığını belirleyemez.
- Kontrol: Kapsamları, rolleri, hesap üyeliğini, kaynak sahipliğini ve uç noktaya özgü erişim gereksinimlerini inceleyin.
- Düzeltme: Entegrasyon için yalnızca gereken izni verin veya doğru yetkili hesabı kullanın.
- Doğrulama: Başarısız işlemi, hesabın kontrol ettiği bilinen bir kaynak üzerinde test edin.
OAuth bearer token'ları için RFC 6750, invalid_token ile insufficient_scope değerlerini birbirinden ayırır. Sağlayıcı bu kurala uyuyorsa ilki token geçerliliğine, ikincisi ise yetkilendirmeye işaret eder. Her tracking API'sinin OAuth veya bu hata alanlarını kullandığını varsaymayın.
6. Bir token'ın süresi dolmuş veya istek imzası geçersiz
Zamana duyarlı kimlik doğrulama, yanlış statik anahtarın ötesinde hata türleri ekler. Bir OAuth erişim token'ının süresi dolabilir. İmzalı bir istek, zaman damgası kabul edilen pencerenin dışına çıktığı veya sunucu farklı bir imza hesapladığı için reddedilebilir.
İmza uyuşmazlıkları, bir istek gövdesini imzalayıp başka bir gövde göndermekten, yolu farklı biçimde kodlamaktan, sorgu parametrelerini değiştirmekten veya yanlış imzalama gizli anahtarını kullanmaktan kaynaklanabilir. Bu kontroller yalnızca imzalı istekleri belgeleyen API'ler için geçerlidir.
- Kontrol: Token süresinin dolmasını ve yenileme sonuçlarını inceleyin. İmzalar için belgelenen kanonik isteği gönderilen tam baytlar ve alanlarla karşılaştırın.
- Düzeltme: Desteklenen akış üzerinden token'ları yenileyin veya alın, sistem saatini senkronize edin ve imzalı istek bileşenlerini kesinleştirdikten sonra imzaları oluşturun.
- Doğrulama: Yeni bir token aldıktan hemen sonra değil, bir sonraki token yenileme sınırında da test edin.
Çok worker'lı sistemlerde, worker'ların kullanılabilir kimlik bilgilerini tekrar tekrar üzerine yazmasını veya birbiriyle yarışan yenileme denemelerini tetiklemesini önlemek için token yenilemelerini koordine edin. Yenileme token'larını normal istek günlüklerinden ayrı ve korumalı tutun.
7. Bir ağ geçidi, güvenlik duvarı veya ağ politikası isteği engelliyor
403, tracking uygulamasının dışından kaynaklanabilir. Olası nedenler arasında IP izin listesi uyuşmazlığı, giden proxy politikası, web uygulaması güvenlik duvarı kuralı veya kendi yetkilendirmesini gerektiren bir erişim ağ geçidi bulunur.
HTML biçimindeki ret sayfası, tanınmayan bir yanıt başlığı veya ağ geçidine özgü bir istek kimliği, reddeden katmanın belirlenmesine yardımcı olabilir. Bunlar ipucudur, kanıt değildir; ağ geçidi günlükleri veya sağlayıcının destek ekibiyle doğrulayın.
- Kontrol: Başarısız dağıtımın genel çıkış IP'sini ve ağ yolunu bilinen çalışan bir ortamla karşılaştırın.
- Düzeltme: İlgili izin listesini, proxy yapılandırmasını veya dar kapsamlı güvenlik kuralını sorumlu altyapı ekibi aracılığıyla düzeltin.
- Doğrulama: Politika değişikliğinden sonra isteği özgün çalışma zamanından tekrarlayın.
TLS sertifikası doğrulamasını devre dışı bırakmayın veya güvenlik kontrollerini geniş biçimde atlatmayın. Tarayıcı CORS hataları da ayrı teşhis gerektirir: reddedilen isteğin bir ön kontrol OPTIONS isteği mi yoksa gerçek API çağrısı mı olduğunu inceleyin. Uzun ömürlü tracking API gizli anahtarları tarayıcı kodunda açığa çıkarılmamalıdır.
Arızayı izole etmek için basit bir istek kullanın
Başarısız çağrıyı belgelenen uç noktaya, yönteme, gerekli kimlik doğrulamaya ve geçerli en küçük yük gövdesine indirgeyin. Aşağıdaki, sağlayıcıya özgü çalışan bir istek değil, genel bir tanılama şablonudur:
curl --include \
--request "$DOCUMENTED_METHOD" \
--url "$DOCUMENTED_ENDPOINT" \
--header "$DOCUMENTED_AUTH_HEADER: $DOCUMENTED_AUTH_VALUE"İşlem gerektiriyorsa gerekli içerik türünü ve gövdeyi ekleyin. Bunu yalnızca kontrollü bir ortamda kullanın: komut bağımsız değişkenleri, terminal kayıtları ve tanılama araçları gizli anahtarları açığa çıkarabilir. Çıktılarını koruyup maskeleyemiyorsanız ayrıntılı izlerden kaçının.
Basit istek başarılı oluyor ancak uygulama başarısız oluyorsa SDK yapılandırmasını, başlık oluşturmayı, yönlendirmeleri, proxy davranışını ve çalışma zamanı gizli anahtarlarını inceleyin. Her ikisi de başarısız oluyorsa kimlik bilgisinin geçerliliğini, uç nokta seçimini, izinleri ve ağ politikasını araştırın. Sonucun bir nedeni belirlemesi için her seferinde tek bir değişkeni değiştirin.
Kontrolleri bir 17TRACK entegrasyonuna uygulama
Bir 17TRACK Tracking API entegrasyonu için resmi API belgeleriyle başlayın ve çağırdığınız işlem için kimlik doğrulama talimatlarını ve istek biçimini eşleştirin. İlişkisiz bir API'den kopyalanmış bir kimlik doğrulama modelini kullanmayın veya tüketici takip sayfasına erişimin API yetkilendirmesini doğruladığını varsaymayın.
Belgelenen isteği sunucunuzdan çıkan istekle karşılaştırın, ardından hem HTTP yanıtını hem de belgelenen yanıt alanlarını inceleyin. Sorunun üst makama iletilmesi gerekiyorsa maskelenmiş bir örnek, zaman damgası, uç nokta, yanıt ayrıntıları ve mevcutsa istek tanımlayıcısını gönderin. API gizli anahtarını rapora koymayın.
Körlemesine yeniden denemeleri durdurun ve kurtarmayı doğrulayın
Kimlik doğrulama hataları, sınırsız bir yeniden deneme döngüsü yerine tanılamayı tetiklemelidir. Açıkça süresi dolmuş bir token için kontrollü yenilemenin ardından sınırlı bir yeniden deneme uygun olabilir. Eksik izinler, iptal edilmiş kimlik bilgileri veya engellenmiş bir ağ yolu için yeniden denemeler yapılandırmayı düzeltmez.
Bir yazma işlemini yeniden oynatmadan önce sağlayıcının idempotency veya yinelenen işlem davranışını kontrol edin. Bir aracının özgün sonucu belirsiz hâle getirdiği durumlarda bu önemlidir.
Kurtarma; amaçlanan işlem özgün dağıtımdan başarılı olduğunda, ilgili tüm worker'lar doğru yapılandırmayı kullandığında ve izleme sistemi devam eden kimlik doğrulama hataları göstermediğinde tamamlanmış olur. Kimlik bilgilerini açığa çıkarmadan etkilenen uç noktayı ve ortamı belirleyen uyarılarla HTTP durumunu ve uygulama düzeyindeki hataları ayrı ayrı izleyin.
SSS
İstek neden yerel olarak çalışıyor ancak üretimde başarısız oluyor?
Gizli anahtar sürümlerini, temel URL'leri, giden proxy'leri, çıkış IP'lerini, sistem saatlerini ve çalışma zamanı yapılandırmasını karşılaştırın. Yerel başarı, bir istek yolunun çalıştığını gösterir; üretimin aynı isteği gönderdiğini veya aynı izinlere sahip olduğunu göstermez.
Hemen yeni bir API anahtarı oluşturmalı mıyım?
Mevcut kimlik bilgisi geçersiz, iptal edilmiş veya açığa çıkmış olabilecek durumda değilse hayır. Önce doğru uç noktaya gerekli biçimde ulaşıp ulaşmadığını kontrol edin. Gereksiz döndürme, mevcut anahtara hâlâ bağlı olan diğer hizmetlerde hatalara yol açabilir.
Yanlış bir takip numarası 401 veya 403'e neden olabilir mi?
Geçersiz bir takip numarası normalde geçersiz kimlik doğrulamanın kanıtı değil, doğrulama veya kaynak düzeyinde bir sorundur. Ancak bir gönderiye erişim hesap sahipliğiyle kısıtlanabilir. Yalnızca numaraya göre tanı koymak yerine sağlayıcının belgelenmiş hata ayrıntılarını kullanın.
403, API aboneliğimin süresinin dolduğu anlamına mı gelir?
Hayır. Abonelik veya yetki kısıtlamaları, yalnızca sağlayıcı bunları belgeliyor veya belirli bir mesaj döndürüyorsa olası nedenlerden biridir. İzinler, hesap bağlamı ve güvenlik politikaları da reddetmeye neden olabilir. Yalnızca HTTP durumuna dayanarak faturalandırma sorunu çıkarımı yapmayın.
Bir destek talebine neleri eklemeliyim?
UTC zaman damgasını, yöntemi, uç noktayı, ortamı, HTTP durumunu, maskelenmiş yanıt gövdesini, istek kimliğini ve sorunun basit bir istekle yeniden oluşturulup oluşturulamadığını ekleyin. Son dağıtımları veya kimlik bilgisi değişikliklerini açıklayın. Gizli anahtarları hariç tutun ve tanılama için gerekmeyen gönderi verilerini maskeleyin.
Kaynaklar
- RFC 9110: HTTP Semantics — HTTP kimlik doğrulaması, başlık semantiği ve 401 ile 403 tanımları.
- RFC 6750: OAuth 2.0 Bearer Token Usage — bearer token hata yanıtları, geçersiz token'lar ve yetersiz kapsam.
- 17TRACK API documentation — 17TRACK API isteğinin uygulanması ve sorun giderilmesi için sağlayıcıya özgü başvuru.


