Pazaryeri entegrasyonlarında çalışan her e-ticaret operasyonunun ortak gerçeği şudur: bir API çağrısı, beklemediğiniz bir anda hata döndürür ve binlerce ürünün stok güncellemesi, fiyat senkronizasyonu veya sipariş alımı durur. 2026 yılında Türkiye'de aktif e-ticaret işletmelerinin %78'i en az bir pazaryeri entegrasyonu kullanıyor ve bu entegrasyonların her birinde günlük ortalama 3-7 farklı API hata kodu ile karşılaşılıyor.
Bu rehberde HTTP 401, 403, 429, 500, 502, 503 ve 504 hata kodlarının her birini tek tek ele alacak; Trendyol, Hepsiburada, N11 ve Amazon Türkiye API'lerinde sık karşılaşılan senaryoları ve adım adım çözümlerini paylaşacağız. Mayıs 2026 itibarıyla geçerli güncel bilgilerle hazırlanan bu içerik, geliştirici ekiplerinizin saatlerce log incelemekten kurtulması için tasarlandı.
Eğer pazaryeri entegrasyon altyapınızı baştan kurmak ya da mevcut sistemi güçlendirmek istiyorsanız, pazaryeri entegrasyonlarımız sayfasında sunulan hazır çözümleri inceleyebilir ya da ücretsiz kaydolarak dropshipping.gen.tr platformunun API katmanını test ortamında deneyebilirsiniz.
API Erişim Hatası Nedir? Genel Bakış
API erişim hatası, bir uygulamanın başka bir sistemin API uç noktasına gönderdiği isteğe karşılık beklenen başarılı yanıtı (200/201) alamadığı her durumdur. HTTP protokolünde hatalar iki ana sınıfa ayrılır: istemci kaynaklı (4XX) ve sunucu kaynaklı (5XX). Pazaryeri entegrasyonlarında bu iki sınıf birlikte sıkça karşımıza çıkar; çünkü bir isteği hatalı oluşturmuş olabileceğiniz gibi, pazaryerinin sunucusu da geçici olarak yanıt veremiyor olabilir.
4XX ve 5XX Arasındaki Temel Fark
4XX hatalarının çözümü genellikle istemci tarafındadır: yanlış token, eksik header, geçersiz parametre, kota aşımı gibi. 5XX hatalarının çözümü ise pazaryeri tarafındadır; ancak istemcinin uygulayacağı doğru retry mantığı, kullanıcı deneyimini ve veri tutarlılığını korur. Ayrımı yapmadan körü körüne tekrar deneme yapmak, hesabınızın geçici olarak askıya alınmasına bile yol açabilir.
"Bir API hatasının iki kez tekrarlanması koşuldur, üç kez tekrarlanması durumunda ise kesinlikle bir mantık hatası vardır." — Pazaryeri entegrasyon mühendisliği, 2026 yaklaşımı
Pazaryeri API Hatalarının Genel Anatomisi
Türkiye'deki büyük pazaryerlerinin (Trendyol, Hepsiburada, N11, Amazon TR, Çiçeksepeti, Pazarama) API'leri OAuth 2.0 ya da Basic Authentication ile çalışır. Hataların büyük çoğunluğu üç ana noktada oluşur: kimlik doğrulama, hız sınırı (rate limit) ve veri doğrulama (validation). Her pazaryerinin kendine özgü kuralları olsa da temel HTTP standardı tüm motorlarda aynıdır.
HTTP 401 ve 403: Kimlik Doğrulama ve Yetki Hataları
Bu iki hata sıklıkla karıştırılsa da temelden farklıdırlar. 401 Unauthorized, "kim olduğunu kanıtlayamadın" anlamına gelir; sistem sizi tanımıyor. 403 Forbidden ise "kim olduğunu biliyorum ama bu kaynağa erişme yetkin yok" demektir. Çözüm yolları da bu nedenle farklıdır.
401 Hatasının En Sık Üç Nedeni
- Token süresi dolmuş. OAuth 2.0 access token'ları genellikle 1-24 saat geçerlidir. Token expiry sonrası refresh token akışı kurulmadıysa her istek 401 döner.
- API anahtarı yanlış environment'tan kullanılıyor. Sandbox token'ı ile production endpoint'e veya tam tersi, anlık 401 üretir.
- Header formatı bozuk.
Authorization: Bearer xxxxxbeklenen yerde sadecexxxxxgönderilmesi, ya da Basic Auth'da Base64 kodlamasının atlanması.
403 Hatasının Çözümünde Üç Adım
403 aldığınızda öncelikle hangi kaynak için yetki gerektirildiğini doğrulayın. Pazaryerlerinde scope kavramı hayati önemdedir: aynı satıcı hesabı için "ürün okuma" ve "fiyat güncelleme" farklı yetkiler olabilir. Trendyol API'sinde örneğin satıcı paneli üzerinden yetki verilmemiş bir entegratör, ürün listeleme dışında her isteğe 403 alır.
İkinci adım IP whitelist kontrolüdür. Bazı pazaryerleri (özellikle B2B API'leri) yalnızca önceden tanımlı IP adreslerinden gelen isteklere yanıt verir. Sunucu IP değişimi sonrası unutulan whitelist güncellemesi tipik 403 kaynağıdır. Üçüncü adım ise hesap durumu kontrolüdür: askıya alınmış mağazalar tüm 403'e takılır.
HTTP 429: Çok Fazla İstek (Rate Limit Hatası)
Yandex Webmaster verilerine göre "api hatası 429" sorgusu, son 30 günde Türkiye'de 200'ün üzerinde arama hacmine ulaştı. Bu hata türü, API entegrasyonlarında en çok kafa karıştıran hatadır çünkü kodunuzda hiçbir şey yanlış olmamasına rağmen yanıt alamazsınız. Pazaryerleri istek başına saniyede X istek, dakikada Y istek gibi sınırlar koyar.
Pazaryerlerine Göre Yaklaşık Hız Limitleri
| Pazaryeri | Endpoint Türü | Limit (yaklaşık) | Sıfırlama |
|---|---|---|---|
| Trendyol | Ürün/Stok/Fiyat | ~100 istek/dk | Yuvarlanan dakika |
| Hepsiburada | Listing/Inventory | ~120 istek/dk | Yuvarlanan dakika |
| N11 | SOAP/REST karma | ~60 istek/dk | Sabit dakika |
| Amazon TR | SP-API | Endpoint başına token bucket | Anlık + saatlik |
| Çiçeksepeti | Marketplace API | ~30 istek/dk | Yuvarlanan dakika |
Yukarıdaki rakamlar gözlemsel ortalamalardır; resmi olarak duyurulmamış olabilir ve pazaryeri tarafından önceden uyarı yapılmadan değiştirilebilir. En güncel limitler için ilgili pazaryerinin geliştirici dokümantasyonunu kontrol etmeniz tavsiye edilir.
429 İçin Doğru Yanıt: Retry-After Header'ı
İyi tasarlanmış API'ler 429 ile birlikte Retry-After header'ı döndürür. Bu header, kaç saniye bekleyip tekrar denemeniz gerektiğini saniye veya HTTP-date olarak belirtir. Header'ı dikkate almadan body'i polling yapmaya devam etmek, çoğu zaman geçici 429 hatasını kalıcı IP banına çevirir.
HTTP 500: Sunucu Tarafı Genel Hatalar
500 Internal Server Error, pazaryeri sunucusunda beklenmeyen bir durum oluştuğunu söyler. Sebebini bilmek mümkün değildir çünkü hata pazaryeri tarafındadır. Ancak tetikleyici neyse onu tespit etmek mümkündür.
500 Hatasının Sık Tetikleyicileri
- Beklenmeyen alan tipleri: integer beklenen yere string, boolean beklenen yere "true"/"false" string'i göndermek. Bazı API'ler bunu 400 ile değil 500 ile yanıtlar.
- Çok büyük payload: Tek istekte 1000+ ürün göndermek, bazı endpoint'lerin işlem zamanaşımına uğramasına ve 500 dönmesine neden olur.
- Özel karakter veya encoding sorunu: UTF-8 dışında karakter, kontrol karakterleri, emoji'ler bazı pazaryerlerinde sunucu tarafı hata fırlatır.
- Çakışan idempotency anahtarı: Aynı idempotency-key ile farklı body göndermek bazı API'lerde 500 döner.
500 İçin Retry Mantığı
500 hataları için exponential backoff ile en fazla 3-5 deneme önerilir: 1s, 2s, 4s, 8s, 16s gibi. Aynı isteğin 5 kez 500 döndürmesi, hatanın geçici olmadığını ve büyük olasılıkla payload'unuzda bir sorun olduğunu işaret eder. Bu durumda tekrarlamak yerine alarm/log mekanizmanız devreye girmelidir.
HTTP 502, 503, 504: Geçici Sunucu Sorunları
Bu üç hata kodu, sunucu tarafında yaşanan farklı sorun türlerini ifade eder ve çözüm yöntemleri benzer olsa da kök neden farklıdır.
502 Bad Gateway
502 hatası, pazaryerinin önündeki yük dengeleyicinin (load balancer / reverse proxy) arka uç servisten geçerli yanıt alamadığını gösterir. Genellikle dakikalar içinde kendiliğinden çözülür. Çözüm: 5-30 saniye bekleyip tekrar deneyin.
503 Service Unavailable
503, sunucunun bilinçli olarak hizmet vermediğini söyler: bakım modu, aşırı yük koruması veya planlı duruş. Bu hata genellikle Retry-After header'ı ile gelir. Pazaryerleri büyük kampanyalarda (Black Friday, Çift Çift, Yılbaşı) 503'ü kasıtlı olarak yük yönetimi için kullanır.
504 Gateway Timeout
504, isteğinizin işlenmesi gateway zaman aşımı süresini aştığını gösterir. Çoğu zaman büyük arama sorguları, geniş ürün filtreleri veya pagination'sız listeleme istekleri 504 üretir. Çözüm payload'u küçültmek veya sayfalandırma kullanmaktır.
Trendyol, Hepsiburada, N11 Özelinde Sık Karşılaşılan Hatalar
Türkiye'nin üç büyük pazaryerinin API'leri ile çalışan ekiplerin günlük olarak gördüğü tipik hata desenlerini ve doğrulanmış çözümlerini paylaşıyoruz.
Trendyol API: "Stok güncellenmiyor"
Bu sorunda istek 200 OK döner ama panelde stok değişmez. Sebep çoğunlukla asenkron işlem kuyruğunda gecikme'dir. Trendyol stok/fiyat güncellemelerini batch işler ve onay 5-15 dakika sürebilir. Çözüm: Kontrolünüzü POST dönüşüne göre değil, sonradan GET ile yapın. Acil senaryolar için webhook altyapısını aktif edin.
Hepsiburada API: "Onay reddedildi"
Hepsiburada listing API'si yeni ürün gönderimlerinde otomatik kategori, marka ve özellik doğrulaması yapar. Reddedilme yanıtında errors alanında somut neden bulunur. En yaygın 5 ret nedeni:
- Marka onayı yok (yetkili distribütör belgesi gerekli)
- Zorunlu özellik eksik (ör: cinsiyet, yaş grubu, malzeme)
- Kategori-attribute uyuşmazlığı
- GTIN/barkod tekilliği ihlali
- Ürün açıklamasında yasaklı kelime
N11 API: "Mağaza askıya alındı"
N11 SOAP API geçişli bir REST sunar; bu nedenle hata mesajları SOAP fault formatında gelebilir. SellerSuspendedException mesajı aldığınızda öncelik teknik değil, ticari bir sorun olduğunu gösterir: ödeme bekleyen fatura, performans skoru, müşteri şikayetleri. Çözüm satıcı paneli üzerinden veya destek talebi ile iletilir.
Retry Stratejileri: Exponential Backoff ve Circuit Breaker
API hatalarının %80'i geçicidir; doğru retry stratejisi ile çözülür. Yanlış retry ise hesabınızı askıya aldırabilir. Doğru yaklaşım exponential backoff with jitter'dır.
Exponential Backoff Formülü
Her başarısız denemenin ardından bekleme süresi katlanır: bekleme = min(maxBekleme, baseBekleme * 2^denemeNo + rastgele_jitter). Jitter eklemek, aynı anda binlerce client'ın aynı saniyede tekrar denemesini önler (thundering herd).
| Hata Türü | Maks Deneme | Strateji |
|---|---|---|
| 429 Rate Limit | Retry-After header kadar | Bekle ve dene |
| 500/502 | 3-5 | Exp. backoff + jitter |
| 503 | Retry-After veya 5 dk | Bekle ve dene |
| 504 | 2-3 | Önce kaynak kontrolü, sonra retry |
| 401/403 | 0 (ya da token yenile) | Retry yapma |
| 400/404/422 | 0 | İstek hatalı, tekrar denemek anlamsız |
Circuit Breaker Deseni
Bir endpoint art arda 5-10 kez başarısız olduğunda, devreyi açın ve belirli bir süre (örn. 30 sn - 2 dk) hiç istek göndermeyin. Bu süre boyunca isteği sıraya alın veya kullanıcıya "geçici sorun" mesajı gösterin. Süre sonunda 1 deneme daha yapın; başarılıysa devreyi kapatın, değilse süreyi uzatın. Bu desen pazaryeri yan etkilerini sizin sisteminize taşımaz.
dropshipping.gen.tr API Sağlığı ve İzleme
Pazaryeri entegrasyonlarınızı kendiniz baştan kurmak yerine, hazır altyapı kullanmak teknik borcu ciddi şekilde azaltır. dropshipping.gen.tr platformu Trendyol, Hepsiburada, N11, Amazon Türkiye ve Çiçeksepeti API'lerini tek panel üzerinden yönetmenizi sağlar.
Platform İçi Hata İzleme
Platformumuzda her API çağrısı loglanır: zaman damgası, endpoint, HTTP status, retry durumu, başarısızlık nedeni. Tedarikçi ve bayi panellerinde "Entegrasyon Sağlığı" sekmesinden son 24 saatlik hata oranınızı, en sık görülen hata kodunuzu ve sistemin önerdiği aksiyonu görebilirsiniz.
X-Request-Id header'ını kaydetmeyi unutmayın. Pazaryerine destek talebi açtığınızda bu ID, sorununuzun saniyeler içinde çözülmesini sağlar; aksi halde "tekrar oluştur ve gönder" cevabı alırsınız.
Ücretsiz Sağlık Testi
Ücretsiz kaydolun, hesabınızı pazaryeri API'lerine bağlayın ve sistemin otomatik 7 günlük sağlık raporunu çıkarmasını izleyin. Blog rehberlerimiz ve eğitim içeriklerimiz ile ekibinizi pazaryeri operasyonlarında uzmanlaştırabilirsiniz.
API Hatalarını Önleme: 7 Best Practice
- Idempotency-Key kullanın. Aynı isteğin iki kez işlenmesini engeller. Çoğu pazaryeri bu header'ı destekler.
- Token yenilemeyi proaktif yapın. Süresi dolmadan 5 dakika önce yenileyin.
- Webhook tercih edin, polling'den kaçının. Polling 429'a, webhook 0'a gider.
- Payload boyutunu sınırlayın. Tek istekte 100-500 öğe, daha fazlası değil.
- Tüm yanıtları loglayın. Sadece hata değil, başarılı yanıtların metadata'sını da.
- Test ortamı (sandbox) kullanın. Production'a doğrudan gitmek yerine.
- Versiyon kilidi koyun. API
v2kullanıyorsanız header'daAPI-Version: 2gönderin; pazaryeri yeni versiyon yayınladığında patlama yaşamazsınız.
Bu Yazıdan Çıkarımlar
- 4XX hataları istemci, 5XX hataları sunucu kaynaklıdır; çözüm yolları farklı, retry mantığı farklıdır.
- 429 hatasında
Retry-Afterheader'ı belirleyicidir; agresif retry hesabı banlatır. - Trendyol stok 200 dönmesine rağmen güncellenmiyorsa neden teknik değil, asenkron kuyruktur.
- Idempotency-Key, webhook ve circuit breaker üçlüsü, pazaryeri entegrasyonunun temel taşlarıdır.
- 500 alındığında her zaman önce payload doğrulayın; %15'i aslında istemci kaynaklıdır.
Sıkça Sorulan Sorular (SSS)
API hatası 429 aldığımda ne kadar beklemem gerekir?
Yanıttaki Retry-After header'ında belirtilen süreyi kullanın. Header yoksa konservatif bir yaklaşımla 60 saniye bekleyin. Bu süre içinde aynı endpoint'e istek atmaktan tamamen kaçının; tek bir isteği değil, kuyruğunuzdaki tüm istekleri durdurun. Trendyol, Hepsiburada gibi büyük pazaryerleri 429'a karşı agresif davrananları geçici olarak banlar.
500 hatası alıyorum ama isteğimde sorun göremiyorum, ne yapmalıyım?
İlk olarak request payload'unuzu eksiksiz doğrulayın: alan tipleri, zorunlu alanlar, character encoding (UTF-8). 500 hatalarının yaklaşık %15'i aslında istemci kaynaklıdır ve API'nin yetersiz hata işleme katmanı yüzünden 500 olarak görünür. Sonra exponential backoff ile 3-5 kez tekrar deneyin. Hata 5 kez de tekrar ediyorsa pazaryerinin destek hattına X-Request-Id ile birlikte başvurun.
401 ve 403 arasındaki fark nedir, hangisinin çözümü daha kolaydır?
401 "kim olduğunu kanıtlayamadın" anlamına gelir; çözümü genellikle token yenileme veya doğru anahtarı göndermektir. 403 ise "kim olduğunu biliyorum ama bu kaynağa yetkin yok" demektir; çözümü genelde pazaryeri panelinden yetki verilmesini, IP whitelist eklenmesini veya ticari bir engelin (askı, ödeme) kaldırılmasını gerektirir. 401 teknik, 403 çoğunlukla idari bir sorundur.
Trendyol API'sinde stok güncelleme isteğim 200 OK dönüyor ama panelde değişmiyor, hata mı var?
Hayır, beklenen davranıştır. Trendyol stok ve fiyat güncellemelerini asenkron olarak işler; isteğin alındığını 200 ile teyit eder ama gerçek güncelleme batch kuyrukta sıraya girer. Tipik onay süresi 5-15 dakikadır. Kritik senaryolar için webhook altyapısını etkinleştirip price-and-inventory-changed olayını dinleyin.
Hepsiburada onay reddediyor, hata mesajı kategori uyuşmazlığı diyor, nasıl çözerim?
Hepsiburada her ürün için kategori-attribute uyumu zorunludur. Reddedilen üründe gönderdiğiniz attribute'ları o kategorinin category-attributes endpoint'inden gelen zorunlu listesi ile karşılaştırın. Eksik veya tip uyumsuz attribute'lar tipik ret nedenidir. Marka onayınız yoksa marka yetki sürecini de tamamlamanız gerekir.
Pazaryeri API'sinden 503 alıyorum sürekli, hesabım banlandı mı?
Hayır, 503 ban değildir; sunucunun planlı veya plansız hizmet veremediği durumdur. Yanıttaki Retry-After süresini bekleyin. Eğer 503 saatlerce sürüyorsa pazaryerinin status sayfasını veya geliştirici duyurularını kontrol edin; büyük bakım çalışması olabilir. Ban durumu genelde 401 veya özel bir error code ile gelir, 503 ile değil.
N11 SOAP API'si REST'e geçti mi, eski entegrasyonum çalışmaya devam edecek mi?
N11 hâlâ SOAP API'sini destekliyor ancak yeni geliştirmeler için REST endpoint'lerini öneriyor. Mevcut SOAP entegrasyonlarınız 2026 itibarıyla çalışmaya devam ediyor; ancak yeni özellikler önce REST üzerinde yayınlanıyor. Uzun vadede REST'e geçişi planlamanız tavsiye edilir.
Sonuç ve Sonraki Adımlar
API erişim hataları kaçınılmazdır; ancak doğru anlaşıldığında ve ele alındığında e-ticaret operasyonunuzun normal akışına müdahale etmezler. Bu rehberde 401, 403, 429, 500, 502, 503 ve 504 kodlarının her birini tek tek inceledik; Trendyol, Hepsiburada, N11 özelinde tipik desenleri ve pratik çözümleri paylaştık. Anahtar mesaj şudur: kör retry değil, akıllı retry; reaktif değil, proaktif izleme.
Pazaryeri entegrasyonu yönetimini sıfırdan kurmak yerine, doğrulanmış API katmanı, otomatik hata işleme ve canlı izleme sunan bir platforma geçmek istiyorsanız dropshipping.gen.tr'ye ücretsiz kaydolun. Tedarikçi ağımız, ürün kataloğumuz ve fiyatlandırma seçeneklerimiz ile bayi ve tedarikçilerimiz Türkiye'nin önde gelen pazaryerlerinde sorunsuz satış yapıyor.
Daha fazla teknik içerik için blog rehberlerimizi ziyaret edin; mayıs 2026 itibarıyla 100'ü aşkın güncel rehber sizleri bekliyor.
Dropshipping Uzmanı
dropshipping.gen.tr Uzman Editör
Yayın: 5 Mayıs 2026
Hemen Başlayın
dropshipping.gen.tr platformuna ücretsiz kaydolun, binlerce doğrulanmış tedarikçiye erişin ve hemen satışa başlayın.