Hatalar ve Limitler

Public API'nin hata gövdesi, durum kodları, hız sınırları ve boyut sınırları. Hangi isteğin neden reddedildiğini anlamak için önce Kimlik Doğrulama ve Erişim sayfasındaki sıraya, sonra buradaki tablolara bakın.

Hata gövdesi

Hata yanıtları bir JSON nesnesidir:

{
  "statusCode": 400,
  "timestamp": "2026-10-09T09:12:00.000Z",
  "path": "/api/v1/public/sites/SITE_KEY/events/batch",
  "method": "POST",
  "message": "Validation failed",
  "errors": ["events.0.name: name must be a string"]
}

Alan	Anlamı
statusCode, timestamp, path, method	Her hatada vardır
message	İnsan için İngilizce cümle. Programınız bunun metnine bakmamalı
code	Yalnızca kodlu hatalarda: kararlı, SCREAMING_SNAKE bir ad (MODULE_NOT_ENTITLED, SITE_NOT_VERIFIED, VALUE_TOO_LONG). Programınız bu alana bakmalı
params	Kodlu hatada cümlenin değerleri ({ "siteKey": "..." })
errors[]	Yalnızca doğrulama hatasında: alan.yolu: neden biçiminde satırlar

Sunucu hatası (5xx) hiçbir iç ayrıntı taşımaz.

Durum kodları

Kod	Ne zaman	Yeniden dene
200, 201	Başarı; POST uçları 201 döner. Ama analitik uçlar success: false ile de başarı kodu dönebilir; gövdeye bakın	Hayır
304	Yalnızca SSR ucu: If-None-Match eşleşti	Hayır
400	İstek geçersiz: gövde doğrulaması, zorunlu alan eksik, bilinmeyen alan, sınırı aşan değer	Hayır; düzeltin
401	x-selwise-api-key başlığı hiç gönderilmedi (SSR ve izin uçları)	Hayır
402	Hesabın sözleşmesinde bu modül yok (MODULE_NOT_ENTITLED). Panelde ilgili ekran da görünmez	Hayır; hesap yöneticinizle konuşun
403	Kanal doğrulanmamış, alan adı yetkisiz, API anahtarı geçersiz ya da kapsamı yetersiz (BUSINESS_EVENTS_SCOPE_REQUIRED: iş olayı mobil anahtarla geldi ve geçiş süresi bitti), hesap teslimatı kapalı, ya da kanal imzalı kimliği zorunlu kılmışken traits imzasız bir tarayıcıdan geldi (IDENTITY_NOT_VERIFIED)	Hayır
404	Site anahtarı bilinmiyor, ya da bir kayıt yok (örneğin SITE_USER_NOT_IDENTIFIED, FEED_TOKEN_INVALID)	Hayır
409	Durum çakışması (FEED_SYNC_IN_PROGRESS: aynı besleme için bir senkronizasyon sürüyor)	Evet, bir süre sonra
413	Gövde sınırı aşıldı (aşağıda)	Hayır; küçültün
429	Hız sınırı. IDENTIFY_LIMIT ise bir tarayıcı bir günde çok sayıda farklı müşteri numarasıyla tanıtıldı; ertesi gün açılır	Evet, Retry-After kadar sonra (IDENTIFY_LIMIT hariç)
503	Veritabanı bağlantı havuzu dolu (DB_POOL_EXHAUSTED) ya da bakım penceresi	Evet
504	İstek 30 saniyede tamamlanamadı	Evet, küçülterek

5xx ve 429 geçici sayılır; bir istemci bunları üstel geri çekilmeyle (ör. 1, 2, 4 saniye, en çok birkaç deneme) yeniden denemelidir. 4xx yeniden denemekle düzelmez.

Bilinmeyen alan 400 verir

Sunucu, gövdesini sınıfla doğruladığı uçlarda tanımadığı alanı reddeder; sessizce yok saymaz.

Uç	Gövde doğrulaması
events/batch, users/identify, users/traits, newsletter, contacts/consent, business-events, scenarios/inbox ve inbox/ack, product-metrics/batch, push/subscribe, experiments/track, segments/evaluate	Sınıfla doğrulanır; bilinmeyen alan 400. Sorgu parametreleri sınıfla doğrulanan uçlar da (product-metrics, scenarios/inbox) bilinmeyen parametreyi reddeder
orders	Doğrulanmaz; bilinmeyen alan yok sayılır (yalnızca id alanı 400)
consent	Sınıfla doğrulanır: categories zorunlu, bilinmeyen üst alan 400
search/log, search/click, search/zero-results, recommendations/*	Doğrulanmaz; eksik zorunlu alan 400 ya da 500 olabilir, bilinmeyen alan yok sayılır

Yazmadan denemek: dry-run

Yazma uçlarının çoğu x-selwise-dry-run: 1 başlığını tanır: istek gerçek çağrıyla aynı kimlik doğrulamasından ve gövde doğrulamasından geçer, ama işlem çalıştırılmaz. Hiçbir kayıt yazılmaz, olay kaydedilmez, senaryo kuyruğuna bir şey girmez. Yanıt, ucun kendi başarı koduyla ve şu gövdeyle döner:

{ "dryRun": true, "valid": true, "message": "…", "request": { "orderId": "ORDER_12345" } }

Geçersiz bir istek ise gerçek çağrıdaki hatayı alır (400 ve errors[], 403, 404 ...). Entegrasyonunuzu canlı veriye dokunmadan denemek, CI'da sözleşmeyi doğrulamak ya da dokümandaki Dene paneli için kullanılır. Bir ucun dry-run destekleyip desteklemediği o ucun kutusunda yazar; desteklemeyen bir uca bu başlıkla istek atarsanız 400 (kod DRY_RUN_UNSUPPORTED) alırsınız ve istek çalıştırılmaz.

Hız sınırları

Sınırlar dakika başına, IP başına ve uç başına sayılır: bir ucun kovası, aynı IP'nin başka bir uca yaptığı isteklerle paylaşılmaz. Aşağıdakiler varsayılan değerlerdir.

Uç	Sınır
config, events/batch, product-facts	1000 istek
events/batch (ek)	Ziyaretçi (ya da oturum) başına 120, aynı kanalda bir IP için 1200
ssr/enrichments	API anahtarı başına 6000 (IP değil)
business-events	300
experiments/track, segments/evaluate	120
experiments/assign, scenarios/inbox, scenarios/inbox/ack, push/subscribe, push/unsubscribe, unsubscribe	60
newsletter	20
messaging/.../events (sağlayıcı webhook'u), orders, orders/:orderId/status	600
identify, traits, consent, search/log, search/click, search/zero-results, recommendations/track/*	Sınırsız: veri kaybı olmasın diye. Tek istisna: identify aynı tarayıcıdan (visitorId) günde en fazla 5 farklı müşteri numarası kabul eder, fazlası 429 ve IDENTIFY_LIMIT alır. İmzalı çağrı (İmzalı Kimlik) bu sınıra takılmaz
Diğer her uç (tracking-config, integrations, campaigns, scripts, search, search-config, search/suggestions, recommendations, recommendations/:id/products, product-metrics/*, enrichments, app/enrichments, metrics, contacts/consent, feeds/:token)	100

Yanıtlar X-RateLimit-Limit ve X-RateLimit-Remaining başlıklarını taşır. Aşıldığında 429 ve saniye cinsinden Retry-After döner. Gövde ucun sınırlayıcısına göre biraz farklıdır (ThrottlerException: Too Many Requests ya da { "error": "Too Many Requests", "retryAfter": 12 }); Retry-After başlığına güvenin.

SSR ucu bilerek anahtar başına sayılır: sizin sunucularınız bütün mağaza trafiğini birkaç adresten taşır, IP başına sayılsaydı paylaşılan kovayı saniyeler içinde tüketir ve widget'ınızı, olay akışınızı ve aramanızı da durdururdu.

429 alırsanız

Sebep	Çözüm
Olayları tek tek gönderiyorsunuz	events/batch ucunda 50-200 olayı tek istekte toplayın
Sunucudan arama, öneri ya da ürün sayısı çağrısı	Yanıtı kendi önbelleğinizde 1-5 dakika tutun; tek IP'den çıkan trafik tek kovaya yazılır
Döngü içinde sipariş	Siparişleri orderId ile tekilleştirip yayın
Hâlâ sınırda	Hesap yöneticiniz ortamın sınırlarını yükseltebilir; kendi tarafınızda Retry-After kadar bekleyin

Widget bu sınırlara zaten uyar; sorun genellikle kendi yazdığınız sunucu tarafı entegrasyonlarda çıkar.

Boyut sınırları

Sınır	Değer	Aşılırsa
JSON istek gövdesi (besleme hariç)	Genel varsayılan 100 KB	413 ve kod ENTITY_TOO_LARGE; mesaj sınırı söyler
Besleme gönderimi (her biçim, JSON dahil)	50 MB	413 ve kod FEED_BODY_TOO_LARGE
events/batch	200 olay, olay başına 2 KB metadata	400
contacts/consent	500 kayıt	400
product-metrics/batch	50 ürün	400
SSR yanıtı	256 KB markup	Kural sınırında kesilir
Müşteri kimliği (siteUserId, externalId)	64 karakter	400 (kimliklendirmede), siparişte bağlantı düşer
Ürün kodu	100 karakter	Zenginleştirmede boş yanıt, olaylarda kabul edilir ama eşleşmez

Zaman aşımı

İstekler 30 saniyede tamamlanmazsa 504 döner. Veri aktarımı gibi büyük işlemler kendi uçlarında daha uzun süre alır; satır içi gönderimde istek başına 1000 kayıt sınırı vardır, bkz. Veriyi Hazırlama.

Sunucu taraflı çağrılarda (özellikle SSR) kendi zaman aşımınızı kısa tutun: Sunucu Taraflı Render API.

localhost

Yerel geliştirme adresinden gelen Origin/Referer üretimde kabul edilmez. Bu kapatılamaz: kabul edilseydi herkes kendi makinesinden sizin sitenizin adına veri gönderebilirdi. Yerel geliştirme için ayrı bir test kanalı tanımlayın.

Sırada ne var

• Kimlik Doğrulama ve Erişim
• Takip Sorunları — Ağ sekmesinde bir hatayı teşhis etme