Error codes & troubleshooting

HTTP codes, the error dictionary, retry rules and common pitfalls.

Error body

Errors are returned as application/problem+json. Machines read error; message is for humans (in Turkish); branch on the code, not on the text. Every error body also carries requestId (the same value as the X-Request-Id header): include it in support requests. Endpoint-specific extra fields (field, reason, current, allowed, accepted, maxItems, maxLength) come at the start of the body.

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 codes

Alan	Tip	Açıklama
`200`	processed	On bulk endpoints and on the dispute response, check the per-item results too; 200 does not mean "everything succeeded".
`201`	created	Returned by `POST /orders/test`.
`202`	accepted	Çarşı bulk writes. The outcome is not in this response; read it from `GET /batches/{id}`.
`304`	not modified	`If-None-Match` matched on the menu; use your cached copy.
`400`	bad request	You get the same result until you fix it; do not retry.
`401`	unauthorized	Authentication failed or the key does not belong to this environment.
`403`	header	The `X-Integrator` header is required on every request.
`404`	not found	The record does not exist or does not belong to this business; or the endpoint does not exist for this business's vertical (`not_available_for_vertical`). The `error` field tells them apart.
`405`	method	Unsupported method. This response is produced by the framework and carries no problem+json body.
`409`	conflict	Invalid state transition, or picking not closed. Read `allowed` and `current` from the response.
`413`	too large	The body exceeded the 1 MB limit; for `PUT /webhook` the limit is 16 KB.
`422`	unprocessable	`idempotency_key_reuse`: the same key was used with another operation or a different body.
`429`	rate limited	Wait for `Retry-After` seconds; `reason` names which limit applied.
`5xx`	transient	Retry with exponential backoff. For a `500 internal`, open a support request with the `requestId`.

Error dictionary

The tables below are read from the descriptions of the Hata, TopluIsSonucu and ToplamaSonucu schemas in the OpenAPI document; they are the same source. — means the message varies by situation or is empty.

Request errors

Code	Status	Message (Turkish)	Explanation (from the OpenAPI document)
`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şı bulk job: item errors, pending items and warnings

The values of errors[].errorCode, pending[].pendingReason and warnings[].code; the field column says which array they come from. Branch on the code.

Code	Array	Message (Turkish)	Explanation (from the OpenAPI document)
`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ı.

Picking: item results

The values of results[].error in the POST /orders/{id}/picking response. The 409 codes returned on closing (picking_incomplete, nothing_found, exceeds_band) are in the request-errors table above.

Code	Array	Message (Turkish)	Explanation (from the OpenAPI document)
`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.

Restaurant menu item results (status)

Alan	Tip	Açıklama
`applied`	status	Applied and live.
`pending_review`	status	Accepted but under review; on an above-threshold price increase the live price does not change, and a suspicious product does not appear on sale until approved. Show it as "pending" on your side.
`not_found`	status	No such record for this business; refresh the menu.
`invalid`	status	The value is invalid; `message` gives the reason. Do not resend without fixing it.

Retry rules

Apply the same classification we use for webhook delivery:

Retry: 5xx, 408, 429, network errors, timeouts, with exponential backoff and jitter.
Do not retry: other 4xx. The same request yields the same result.

The quota is 50 requests per 10 seconds per service group and key; your remaining budget arrives on every response that reaches authentication in RateLimit-Remaining. Details: Service limits.

Common pitfalls

Every request returns 403. The X-Integrator header must be 1–30 characters: letters, digits and spaces without Turkish characters (example: Ornek POS).
My webhook signature fails. The secret starts with whsec_; what follows must be base64-decoded and used as raw bytes. See Webhooks.
I cannot map an order line to my product. Map by identifier, never by name: items[].id on a restaurant, clientReferenceId on Çarşı. See Order lifecycle.
I updated a price and nothing changed. The item result may be pending_review: increases above a threshold go to review and the live price is kept.
I received the same order twice. Delivery is at-least-once. Deduplicate on webhook-id; there is no ordering guarantee, and order.status in the body is authoritative (exception: with deliveryFailed.completedSale: true, cancelled is not a cancellation but a sale paid online).
My Çarşı bulk job completed but the products are missing. Check the pending[] array: a product missing a required attribute is written but not put on sale. Resending does not help; supply the missing field.