Trendyol API hata kodları ve statüleri ne anlama gelir?

HTTP durum kodları (resmî tablo)

Aşağıdaki açıklamalar Trendyol’un geliştirici dokümanındaki Hata Kodları sayfasından aynen aktarılmıştır; “ne yapmalı” sütunu yalnız resmî sayfalarda yazan öneriyi verir. 2xx kodları isteğin alındığını gösterir; ürün ve stok-fiyat servislerinde bu, işlemin bittiği anlamına gelmez, toplu işlem sonucu ayrıca sorgulanır.

401, 403 ve 429: kimlik doğrulama ve hız sınırı

401 yanıtının gövdesinde “ClientApiAuthenticationException” görünür; satıcı numarası, API Key ya da API Secret eksik ya da yanlıştır. 403 iki nedenle gelir: hatalı uç nokta ya da parametre, ya da User-Agent başlığının olmaması; Trendyol, User-Agent bilgisi olmayan isteklerin 403 ile engellendiğini yazar (biçim: “Satıcı Id - Entegrasyon Firması İsmi” ya da “Satıcı Id - SelfIntegration”).

429, aynı uç noktaya 10 saniyede 50 isteğin aşılmasıdır. 14 Eylül 2026’dan itibaren ürün servisleri grup bazlı dakika sınırlarına tabidir ve fiyat güncellemesinde barkod bazlı dakikada 30 istek sınırı vardır. Stok-fiyat servisinde değişmeyen aynı gövde 15 dakika boyunca tekrarlanamaz.

Sipariş paketi statüleri

Siparişte hata kodu değil statü vardır. Statüler ve resmî açıklamaları aşağıdadır; Picking ve Invoiced statülerini satıcı besler. Kısmi iptal ya da paket bölünmesinde sipariş numarası aynı kalır, paket bozulur ve yeni paket kimliği ile kargo barkodu oluşur.

Tedarik edememe neden kodları (500–506)

Satıcı paketteki ürünü gönderemiyorsa iptali neden koduyla bildirir: 500 Stok tükendi; 501 Kusurlu/Defolu/Bozuk ürün; 502 Hatalı fiyat (yanlış fiyat beslenmesi durumunda); 504 Entegrasyon hatası (entegrasyon firmasından kaynaklı hatalı fiyat ya da stok aktarımı); 505 Toplu alım; 506 Mücbir sebep (doğal afet, hastalık, cenaze vb.). Listede 503 yoktur. Bu iptaller satıcı puanındaki tedarik edememe oranına girer; bildirimden sonra sipariş paketleri yeniden çekilmelidir, çünkü aynı sipariş numarasıyla yeni paket oluşur.

1. İptal edilecek kalemleri ve neden kodunu belirleyin (500–506).
2. Tedarik edememe bildirimi servisine paket kimliğiyle gönderin.
3. Sipariş paketlerini yeniden çekin; yeni paket kimliğini kaydedin.
4. Stok ya da fiyat kaynaklıysa kök nedeni düzeltin; oran satıcı puanını etkiler.

Ürün onay, ret ve listeleme durumları

Onaylı ürün servisinde approved alanı true ya da false döner; false olan ürünlerde onay süreci devam ediyor ya da ürün reddedilmiş olabilir. Onaysız ürün servisinde status alanı rejected ya da pendingApproval’dır; docNeeded true ise belge panelden yüklenir ve ret nedeni rejectReasonDetails alanındadır. Onaylı ürünlerde status archived, blacklisted, locked, onSale ya da notOnSale olabilir; onSale true olan ürün satıştadır.

Kilit nedenleri arasında düşük ya da yüksek fiyatlandırma, kritik fiyat hatası ve tedarik edememe sayılır; kilit kaldırma servisi örnek hata gövdeleri olarak invalid.barcode (400) ve product.not.found (404) verir. Satıcı Bilgi Merkezi en sık ret sebeplerini görsel, marka, kategori, satış kuralı ve yasaklı kelime olarak sıralar.

Toplu işlem sonuçları: SUCCESS ve FAILED

Ürün yaratma, güncelleme ve stok-fiyat istekleri kuyruğa alınır ve toplu işlem numarası döndürür. Toplu işlem kontrol servisinde batch durumu IN_PROGRESS ya da COMPLETED, kalem durumu SUCCESS ya da FAILED’dır; başarısız kalemlerin nedeni failureReasons alanındadır ve sonuç 4 saat boyunca görüntülenir. Stok-fiyat güncellemesinde batch düzeyinde durum dönmez; kalem bazında bakılır.

Fatura, iade ve webhook durumları

Fatura durumu (invoiceStatus) NotInvoiced, Received, Rejected ya da Invoiced’dır; Rejected durumunda Türkiye siparişi için fatura silinip yeniden gönderilir. Fatura bağlantısı gönderiminde 409, pakete faturanın zaten eklenmiş olması ya da bağlantının başka pakette kullanılması demektir.

İade kalem durumları Created, WaitingInAction, Accepted, Rejected, Cancelled, Unresolved, InAnalysis ve WaitingFraudCheck’tir; 48 saat içinde aksiyon alınmayan iade otomatik kabul edilir. Webhook’ta başarısız bildirim her 5 dakikada bir yeniden denenir, sürerse webhook pasife alınır ve iki e-posta gönderilir; en çok 15 webhook tanımlanır ve uç nokta aynı olayı iki kez alabileceğini varsaymalıdır.

Yekuna bu kodları nasıl gösterir?

Yekuna’da kanaldan gelen teknik hata kodları sadeleştirilir; ne olduğu ve ne yapmanız gerektiği yazılır. Entegrasyonlar bölümünden Trendyol’u bağlayıp bağlantıyı test edersiniz; bilgiler şifrelenerek saklanır.

Sık sorulanlar

Canlıda 403 alıyorum, neden?

Hatalı uç nokta ya da parametre, ya da User-Agent başlığı eksik. Ürün servislerinde V1 kullanıyorsanız V2’ye geçin; Satıcı Bilgi Merkezi V1’in Ağustos 2026’da, geliştirici ana sayfası 15 Ekim 2026’da kapanacağını yazar.

200 döndü ama ürün satışta değil?

Toplu işlem numarasını 4 saat içinde sorgulayın; kalem FAILED ise failureReasons’ı okuyun. SUCCESS ise approved ve onSale alanlarına bakın.

Tedarik edememe hangi kodla bildirilir?

reasonId 500–506 (503 yok). Bildirimden sonra paket bozulur; sipariş paketlerini yeniden çekin.

429 aldım, ne kadar beklemeliyim?

Resmî sayfa bekleme süresi vermez; sınır aynı uç noktaya 10 saniyede 50 istektir, ürün servislerinde grup bazlı dakika sınırları da geçerlidir.

İlgili sayfalar