Hata Kodları ve Sorun Giderme

HTTP kodları, hata sözlüğü, tekrar deneme kuralları ve sık karşılaşılanlar.

Hata gövdesi

Hatalar application/problem+json olarak döner. Makine error alanını okur, message insan içindir (Türkçe); koda göre dallanın, metne göre değil. Her hata gövdesi ayrıca requestId taşır (X-Request-Id başlığıyla aynı değer): destek talebinde bu değeri iletin. Uca özgü ek alanlar (field, reason, current, allowed, accepted, maxItems, maxLength) gövdenin başında yer alır.

JSON

{
  "type": "about:blank",
  "title": "Bad Request",
  "status": 400,
  "error": "too_many",
  "message": "Bir istekte en fazla 1000 kalem gönderilebilir.",
  "requestId": "6f1c2d3e-0000-4000-8000-000000000000",
  "maxItems": 1000
}

HTTP kodları

Alan	Tip	Açıklama
`200`	işlendi	Toplu uçlarda ve talep yanıtında kalem sonuçlarını da kontrol edin; 200 "hepsi başarılı" demek değildir.
`201`	oluşturuldu	`POST /orders/test` döner.
`202`	kuyruğa alındı	Çarşı toplu yazmaları. Sonuç bu yanıtta değil, `GET /batches/{id}` ucunda.
`304`	değişmedi	Menüde `If-None-Match` eşleşti; elinizdeki kopyayı kullanın.
`400`	geçersiz istek	Düzeltmeden aynı sonucu alırsınız; tekrar denemeyin.
`401`	kimlik	Kimlik doğrulanamadı ya da anahtar bu ortama ait değil.
`403`	başlık	`X-Integrator` başlığı her istekte zorunludur.
`404`	bulunamadı	Kayıt yok ya da bu işletmeye ait değil; ya da uç bu işletmenin dikeyinde yok (`not_available_for_vertical`). `error` alanı ayırır.
`405`	yöntem	Desteklenmeyen yöntem. Bu yanıt çerçeve tarafından üretilir ve problem+json gövdesi taşımaz.
`409`	çakışma	Geçersiz durum geçişi ya da toplama kapanmamış. Yanıttaki `allowed` ve `current` alanlarına bakın.
`413`	çok büyük	Gövde 1 MB sınırını aştı; `PUT /webhook` için sınır 16 KB.
`422`	işlenemedi	`idempotency_key_reuse`: aynı anahtar başka bir işlem ya da farklı bir gövdeyle kullanıldı.
`429`	hız sınırı	`Retry-After` kadar bekleyin; `reason` sınırın hangisi olduğunu söyler.
`5xx`	geçici	Üstel backoff ile tekrar deneyin. `500 internal` yanıtındaki `requestId` ile destek talebi açılır.

Hata sözlüğü

Aşağıdaki tablolar OpenAPI belgesindeki Hata, TopluIsSonucu ve ToplamaSonucu şemalarının açıklamalarından okunur; belgeyle aynı kaynaktır. — iletinin duruma göre değiştiğini ya da boş olduğunu söyler.

İstek hataları

Kod	Durum	İleti	Açıklama
`invalid_json`	400	Gövde geçerli JSON olmalı.	Gövde ayrıştırılamadı.
`invalid_body`	400	Geçersiz istek.	Gövde şemaya uymuyor; `field` hatalı alanı gösterir.
`invalid_body`	400	`name` 2–80 karakter olmalı.	Kurye gövdesi; `field: name`.
`invalid_body`	400	`phone` 10–15 rakam olmalı (isteğe bağlı + ile).	Kurye gövdesi; `field: phone`.
`invalid_body`	400	`externalId` en çok 64 karakter.	Kurye gövdesi; `field: externalId`.
`invalid_body`	400	`latitude` -90..90 arası sayı olmalı.	Kurye konumu; `field: latitude`.
`invalid_body`	400	`longitude` -180..180 arası sayı olmalı.	Kurye konumu; `field: longitude`.
`invalid_body`	400	`heading` 0..359 arası sayı olmalı.	Kurye konumu; `field: heading`.
`invalid_body`	400	`recordedAt` ISO 8601 olmalı.	Kurye konumu; `field: recordedAt`.
`invalid_query`	400	`{ad}` {min} ile {max} arasında bir tam sayı olmalı.	Sayı sorgu parametresi; `field` parametreyi gösterir.
`invalid_query`	400	`{ad}` ISO 8601 biçiminde bir zaman olmalı.	Zaman sorgu parametresi.
`invalid_query`	400	`status` şu değerlerden biri olmalı: {liste}.	`GET /orders`; `allowed` izin verilen durumları listeler.
`payload_too_large`	413	İstek çok büyük.	Gövde tavanı 1 MB; `PUT /webhook` için 16 KB.
`integrator_header_required`	403	X-Integrator başlığı zorunludur: 1–30 karakter; Türkçe karakter içermeyen harf, rakam ve boşluk.	Kimlik doğrulamasından önce reddedilir.
`invalid_operator`	400	X-Operator en çok 64 karakter olabilir ve yalnız harf, rakam ile . _ : - içerir; e-posta adresi gönderilmez.	Kimlik doğrulamasından önce reddedilir.
`unauthorized`	401	Kimlik doğrulanamadı.	Anahtar ya da parola geçersiz, anahtar kapalı ya da işletme bağı kopmuş.
`environment_mismatch`	401	—	Anahtar bu ortama ait değil; ileti doğru ortamın adresini verir.
`too_many_requests`	429	İstek sınırı aşıldı. Retry-After başlığındaki süre dolunca yeniden deneyin.	`reason` sınırın türünü söyler.
`not_available_for_vertical`	404	Bu uç yalnız Çarşı işletmelerinde var.	Restoran anahtarıyla Çarşı ucuna istek.
`not_available_for_vertical`	404	Bu uç yalnız restoran işletmelerinde var.	Çarşı anahtarıyla restoran ucuna istek.
`not_found`	404	Kayıt bulunamadı.	Kayıt yok ya da bu işletmeye ait değil.
`not_found`	404	Toplu iş bulunamadı ya da saklama süresi doldu.	`GET /batches/{id}`.
`not_found`	404	Sipariş bulunamadı.	`POST /orders/{id}/return`.
`not_found`	404	Restoran bulunamadı.	`PUT /merchant/working-hours`, restoran.
`not_found`	404	—	`PUT /merchant/working-hours`, Çarşı; ileti boştur.
`not_found`	404	Restoran sahibi bulunamadı.	`POST /disputes/{id}/respond`, restoran.
`not_found`	404	Dükkân sahibi bulunamadı.	`POST /disputes/{id}/respond`, Çarşı.
`internal`	500	İşlem tamamlanamadı. Lütfen tekrar deneyin.	`requestId` ile destek talebi açılır.
`bad_request`	400	`invoiceNumber` veya `invoiceUrl` gerekli.	`PUT /orders/{id}/invoice`.
`bad_request`	400	`invoiceUrl` https:// ile başlamalı.	`PUT /orders/{id}/invoice`.
`bad_request`	400	—	`GET /reviews`; `replyStatus` none, pending, approved ya da rejected olmalı, ileti değerleri sıralar.
`bad_request`	400	Geçersiz gün: "{gün}". Kabul edilenler: mon, tue, wed, thu, fri, sat, sun.	`PUT /merchant/working-hours`.
`bad_request`	400	"{gün}" için saatler "HH:MM" biçiminde olmalı (ör. 09:00).	`PUT /merchant/working-hours`.
`bad_request`	400	"{gün}" için açılış ve kapanış aynı olamaz.	`PUT /merchant/working-hours`.
`invalid_status`	400	Çarşı işletmesinde durum yalnız open ya da closed olabilir.	`PUT /merchant/status`, Çarşı; `accepted` kabul edilen değerleri verir.
`setup_incomplete`	400	—	Restoranın kurulumu tamamlanmadığı için açılamadı; ileti eksiği söyler.
`invalid_action`	400	action şu değerlerden biri olmalı: accept, ready, dispatch, deliver, cancel.	`accepted` kabul edilen değerleri verir.
`reason_required`	400	cancel için reasonCode zorunludur; geçerli kodlar GET /cancel-reasons yanıtındadır.	`cancel` eylemi.
`invalid_reason`	400	Geçersiz iptal sebebi kodu.	`accepted` işletmenin seçebildiği kodları verir.
`invalid_prep_minutes`	400	`prepMinutes` 1 ile 180 arasında bir tam sayı olmalı.	Restoranda `accept`; `accepted` `{ min, max }` verir.
`invalid_occurred_at`	400	`occurredAt` ISO 8601 olmalı; gelecekte, sipariş açılışından ya da bir önceki aşamadan önce olamaz; en fazla 24 saat geriye gidebilir.	`reason` nedenini verir.
`forbidden`	403	—	Durum geçiş kapısı eylemi bu kimlik için reddetti.
`invalid_transition`	409	`{eylem}` eylemi `{durum}` durumundaki siparişte yapılamaz.	`current` ve `allowed` alanları. Yarış durumunda ileti güncel durumu söyler.
`picking_incomplete`	409	Toplama kapanmadan sipariş yola çıkarılamaz. Önce POST /orders/{id}/picking ile toplamayı kapatın.	Çarşı; toplama kapanışında kalem sonucu eksikse ileti eksik sayısını söyler.
`order_closed`	409	Sipariş '{durum}' durumunda; kurye yazılamaz.	`PUT /orders/{id}/courier`; `current` durumu verir.
`order_closed`	409	Sipariş '{durum}' durumunda; konum yazılamaz.	`PUT /orders/{id}/courier/location`; `current` durumu verir.
`courier_not_set`	409	Önce PUT …/courier ile kuryeyi bildirin.	`PUT /orders/{id}/courier/location`.
`dispute_closed`	409	Talep için yanıt süresi doldu ya da talep zaten yanıtlandı.	`POST /disputes/{id}/respond`.
`refund_cap_exceeded`	409	İade tutarı bu talep için izin verilen üst sınırı aşıyor.	`POST /disputes/{id}/respond`.
`conflict`	409	—	Talep başka bir işlemle aynı anda değişti; ileti durumu söyler.
`too_long`	400	Yanıt en fazla 1000 karakter olabilir.	`POST /reviews/{id}/reply`; `maxLength` sınırı verir.
`coupon_reward_wording`	400	Yanıt, kuponu değerlendirmenin karşılığı gibi sunamaz. Kupondan söz edebilirsiniz; ancak kuponu yorumun içeriğine ya da puanına bağlamayın, değerlendirmenin değiştirilmesi veya silinmesi koşuluna bağlamayın ve değerlendirme karşılığında kupon vaat etmeyin.	`POST /reviews/{id}/reply`.
`not_published`	409	Yalnız yayımlanmış yoruma yanıt verilebilir.	`current` yorumun durumunu verir.
`invalid_webhook_url`	400	Webhook adresi kabul edilmedi: {neden}	`PUT /webhook`.
`webhook_not_configured`	409	Önce PUT /webhook ile adres tanımlayın.	`POST /webhook/test`.
`no_menu_items`	409	Restoranın aktif (satışa açık) menü ürünü yok — test siparişi gerçek menü kalemlerinden üretilir.	`POST /orders/test`, restoran.
`no_inventory`	409	Dükkânda satışa açık ürün yok — önce katalog aktarın.	`POST /orders/test`, Çarşı.
`too_many_items`	400	Tek istekte en fazla 100 kalem gönderilebilir (gönderilen: {n}).	Menü yazım uçları.
`empty`	400	En az bir kalem gönderilmeli.	Toplu yazma uçları; `maxItems` sınırı verir.
`too_many`	400	Bir istekte en fazla 1000 kalem gönderilebilir.	Toplu yazma uçları; `maxItems` sınırı verir.
`idempotency_key_reuse`	422	Bu Idempotency-Key başka bir işlem ya da farklı bir gövdeyle kullanıldı.	Toplu yazma uçları.
`nothing_found`	409	Hiçbir ürün bulunamadı. Toplama tamamlanamaz; siparişi 'Tedarik yok' sebebiyle iptal edin (müşteriye tam iade yapılır).	`POST /orders/{id}/picking`, kapanışta.
`exceeds_band`	409	—	Toplama sonucu sipariş tutarını aşıyor; ileti tutarları söyler.
`invalid_lines`	400	Dönüş satırları siparişle uyuşmuyor; her ürün için dönen adet ve dönmeyen adedin sebebi gerekli.	`POST /orders/{id}/return`.
`not_cancelled`	409	Bu sipariş iptal edilmemiş.	`POST /orders/{id}/return`.
`not_failed_delivery`	409	Bu sipariş teslim edilemedi olarak kapatılmamış.	`POST /orders/{id}/return`.
`already_confirmed`	409	Bu siparişin dönüşü zaten onaylanmış.	`POST /orders/{id}/return`.

Çarşı toplu iş: kalem hataları, bekleyenler ve uyarılar

errors[].errorCode, pending[].pendingReason ve warnings[].code değerleri; alan sütunu hangi diziden geldiğini söyler. Koda göre dallanın.

Kod	Dizi	İleti	Açıklama
`invalid_name`	errors	`name` zorunlu ve boş olamaz.	`POST /products`.
`invalid_price`	errors	`price` sıfırdan büyük bir SAYI olmalı (dizge kabul edilmez).	Üst sınır ve yuvarlama kuralı fiyat kapısındandır; ileti sınırı söyler.
`invalid_barcode`	errors	`barcode` 8-14 rakam olmalı. Barkodsuz ürün için `sku` kullanın.	`POST /products`.
`invalid_barcode`	errors	`barcode` 8-14 rakam olmalı.	Fiyat-stok ve durum uçları.
`invalid_stock`	errors	`stock` negatif olmayan bir TAM SAYI olmalı.	Ekleme ve fiyat-stok uçları.
`missing_identity`	errors	`barcode` ya da `sku` zorunlu — kalıcı kimlik olmadan aynı ürün her gönderimde yeniden yaratılır.	`POST /products`.
`missing_identity`	errors	`barcode`, `sku` ya da `clientReferenceId` alanlarından en az biri zorunlu.	Fiyat-stok ve durum uçları.
`invalid_reference`	errors	clientReferenceId en çok 64 karakter olabilir ve yalnız harf, rakam, _ ve - içerir.	`POST /products`.
`invalid_category`	errors	categoryId, GET /categories yanıtında leaf: true olan bir kategori olmalı.	`POST /products`.
`duplicate_reference`	errors	Bu clientReferenceId dükkânda başka bir üründe kullanılıyor.	`POST /products`.
`ambiguous_identity`	errors	barcode, sku ve clientReferenceId farklı ürünleri gösteriyor; tek ürünü gösteren kimlik gönderin.	Fiyat-stok ve durum uçları; gönderilen anahtarlar farklı ürünleri gösteriyor.
`ambiguous_identity`	errors	{alan} dükkânda birden çok ürüne uyuyor; tek ürünü gösteren bir kimlik gönderin.	Fiyat-stok ve durum uçları; tek anahtar birden çok ürüne uyuyor.
`tax_rate_required`	errors	taxRate zorunludur; ürünün KDV oranını işletme belirler (izin verilen oranlar: 1, 10, 20).	`POST /products`.
`invalid_tax_rate`	errors	`taxRate` şunlardan biri olmalı: 1, 10, 20.	`POST /products`.
`already_exists`	errors	Ürün bu dükkânda zaten kayıtlı; fiyat ve stok için PUT /products/price-and-stock kullanın.	`POST /products`; bu uç oluşturur, güncellemez. Fiyat ve stok `PUT /products/price-and-stock`, satış durumu `PUT /products/status` ile değişir.
`not_found`	errors	Bu dükkânda böyle bir ürün yok. Yeni ürün için POST /products kullanın.	Fiyat-stok ve durum uçları.
`empty_update`	errors	`price` ya da `stock` alanlarından en az biri gönderilmeli.	Fiyat-stok ucu.
`invalid_status`	errors	`onSale` alanı `true` ya da `false` olmalı.	Durum ucu.
`invalid_reason`	errors	—	Durum ucu; `onSale: false` iken `reason` kapalı listeden olmalı. İleti geçerli sebepleri sıralar.
`update_failed`	errors	—	Fiyat-stok ve durum uçları; kalem yazılamadı, ileti hatayı kısaltarak söyler.
`ingest_failed`	errors	—	`POST /products`; kalem yazılamadı, ileti hatayı kısaltarak söyler.
`rejected`	errors	—	`POST /products`; kalem kabul edilmedi.
`new_master_review`	pending	—	Yeni ürün kaydı incelemede.
`missing_attribute`	pending	—	Kategorinin zorunlu niteliği eksik; ürün kaydedildi ama satışa çıkmadı.
`restricted_product`	pending	—	Ürün yasaklı ürün şüphesiyle incelemede.
`image_ignored`	warnings	Görsel adresi kabul edilmedi; ürün görseli işletme panelinden yüklenir.	`POST /products`; kalem yazıldı.

Toplama: kalem sonuçları

POST /orders/{id}/picking yanıtındaki results[].error değerleri. Kapanışta dönen 409 kodları (picking_incomplete, nothing_found, exceeds_band) yukarıdaki istek hataları tablosundadır.

Kod	Dizi	İleti	Açıklama
`order_not_pickable`	results	—	Sipariş toplanabilir durumda değil.
`picking_closed`	results	Toplama tamamlandı; kalem değiştirilemez.	Toplama kapandı.
`not_found`	results	Kalem bulunamadı.	`clientReferenceId` siparişte yok.
`invalid_weight`	results	—	Gram tam sayı ve sıfırdan büyük olmalı.
`weight_above_band`	results	—	Tartı kabul edilen aralığın üstünde.
`weight_below_band`	results	—	Tartı kabul edilen aralığın altında.
`not_weighable`	results	Bu kalem tartılı değil — kısmi ADET gir.	Tartılı olmayan kalemde gram.
`partial_not_short`	results	—	Kısmi tartı beklenenden az olmalı.
`note_required`	results	—	Kısmi tartıda not zorunlu.
`invalid_quantity`	results	—	Kısmi adet 1 ile sipariş adedi arasında olmalı.
`substitution_not_allowed`	results	—	Müşteri bu üründe ikame istemedi.
`approval_required`	results	—	Müşteri onayı gerekli; `customerApproved` ile işaretlenir.
`substitute_required`	results	İkame ürünü seçilmedi.	`substituted` için `substituteClientReferenceId`.
`substitute_not_found`	results	İkame ürün bu markette bulunamadı.	İkame ürün dükkânda yok.
`order_changed`	results	—	Sipariş toplama sırasında değişti; yeniden okunur.

Restoran menü kalem sonuçları (status)

Alan	Tip	Açıklama
`applied`	status	Uygulandı, canlıda.
`pending_review`	status	Kabul edildi ama incelemede; eşik üstü fiyat artışında canlı fiyat değişmez, şüpheli üründe ürün onaylanana kadar satışta görünmez. Kendi tarafınızda "beklemede" gösterin.
`not_found`	status	Bu işletmede böyle bir kayıt yok; menüyü tazeleyin.
`invalid`	status	Değer geçersiz; `message` sebebi söyler. Düzeltmeden tekrar göndermeyin.

Tekrar deneme kuralları

Webhook teslimimizde uyguladığımız sınıflandırmanın aynısını siz de uygulayın:

Tekrar deneyin: 5xx, 408, 429, ağ hatası, zaman aşımı; üstel backoff ve rastgelelikle.
Tekrar denemeyin: diğer 4xx. Aynı istek aynı sonucu verir.

Kota servis grubu ve anahtar başına 10 saniyede 50 istektir; kalan bütçeniz kimlik doğrulamasına ulaşan her yanıtta RateLimit-Remaining ile gelir. Ayrıntı: Servis Limitleri.

Sık karşılaşılanlar

Her istekte 403 alıyorum. X-Integrator başlığı 1–30 karakter olmalı; Türkçe karakter içermeyen harf, rakam ve boşluk (örnek: Ornek POS).
Webhook imzam doğrulanmıyor. Sır whsec_ ile başlar; önekten sonrası base64 çözülüp ham bayt olarak kullanılmalıdır. Bkz. Webhook.
Sipariş kalemini ürünümle eşleyemiyorum. Ada göre değil kimliğe göre eşleyin: restoranda items[].id, Çarşı'da clientReferenceId. Bkz. Sipariş Yaşam Döngüsü.
Fiyat güncelledim ama menüde değişmedi. Kalem sonucu pending_review olabilir: eşik üstü zamlar incelemeye düşer ve canlı fiyat korunur.
Aynı siparişi iki kez aldım. Teslim en az bir kez yapılır. webhook-id ile tekilleştirin; sıra garantisi yoktur, gövdedeki order.status otoritedir (istisna: deliveryFailed.completedSale: true ise cancelled iptal değil, online ödenmiş satıştır).
Çarşı toplu işim tamamlandı ama ürünler görünmüyor. pending[] dizisine bakın: zorunlu niteliği eksik ürün yazılır ama satışa çıkmaz. Tekrar göndermek çözmez; eksik alanı tamamlayın.