# Hata kodları

siparis.app API hataları `application/problem+json` biçimindedir (RFC 9457). İstek adresi `https://api.siparis.app/v1`; hata yanıtında `status` HTTP durumunu, `code` kararlı programatik kodu, `detail` açıklamayı, `errors` hatalı alanları, `request_id` destek takip kimliğini taşır. Karar verirken Türkçe metni ayrıştırmayın; `code` kullanın.

Örnek HTTP 422 yanıtı (uydurma veri):

```json
{
  "code": "invalid_date_range",
  "detail": "Zaman aralığının başlangıcı bitişten sonra.",
  "errors": [],
  "request_id": "req_ornek_20261016",
  "status": 422,
  "title": "Unprocessable Entity",
  "type": "urn:siparis:problem:invalid_date_range"
}
```



Hatalı girdiyi değiştirmeden tekrar göndermeyin; geçici hata ve hız sınırı için [tekrar kurallarını](https://developer.siparis.app/hiz-siniri) uygulayın.

## Ortak hatalar

Bu kodlar her uçta olabilir (anahtar, izin, istek biçimi, hız sınırı, tekrar anahtarı); uç sayfalarında tekrar yazılmaz. Uç sayfası yalnız o uca özgü hataları listeler.

| HTTP | code | Anlamı | Nasıl düzelir? |
| --- | --- | --- | --- |
| 400 | `invalid_request` | İstek biçimi geçersiz. | Gövdeyi ve başlıkları kontrol edin; Idempotency-Key en çok 200 karakterdir. |
| 400 | `key_in_query` | Anahtar URL sorgusuna yazılmış. | Anahtarı yalnız Authorization: Bearer başlığında gönderin. |
| 400 | `unsupported_api_version` | İstenen sürüm desteklenmiyor. | Siparis-Version başlığını v1 yapın veya kaldırın. |
| 401 | `invalid_api_key` | Anahtar geçersiz, süresi dolmuş veya iptal edilmiş. | Panelde açık bağlantı oluşturun/döndürün; sunucu ortamındaki anahtarı güncelleyin. |
| 401 | `test_key_in_live` | Deneme anahtarı canlı ortamda kullanılamaz. | spk_test_ anahtarını https://api.sandbox.siparis.app/v1 adresinde kullanın. |
| 401 | `live_key_in_sandbox` | Canlı anahtar deneme ortamında kullanılamaz. | Deneme panelinde ayrı bir spk_test_ anahtarı oluşturun. |
| 403 | `insufficient_scope` | Gerekli kapsam eksik. | İşletme sahibinden uç ve alt kaynakların okuma kapsamlarını isteyin. |
| 404 | `not_found` | Kayıt/uç yok veya anahtarın marka sınırında görünmüyor. | Kimlik önekini, markayı ve arşiv süzgecini kontrol edin. |
| 405 | `method_not_allowed` | Uç HTTP yöntemini desteklemiyor. | Başvuruda yazılı GET/POST/PATCH yöntemini kullanın. |
| 422 | `validation_error` | İstek alanı veya değeri geçersiz. | errors içindeki field ve code değerlerine göre isteği düzeltin. |
| 429 | `rate_limit_exceeded` | Okuma veya hatalı anahtar hız sınırına ulaşıldı. | Retry-After saniyesini bekleyin; artan bekleme ve rastgele gecikme kullanın. |
| 500 | `internal_error` | Sunucu isteği tamamlayamadı. | Güvenle tekrarlanabilen isteği artan beklemeyle deneyin; sürerse request_id ile destek alın. |
| 503 | `service_unavailable` | Servis geçici olarak yoğun veya erişilemiyor. | Retry-After kadar bekleyip güvenle tekrarlanabilen isteği deneyin. |
| 400 | `idempotency_key_required` | Tekrar anahtarı eksik. | Idempotency-Key başlığına yeni iş için benzersiz değer yazın. |
| 409 | `idempotency_in_progress` | Aynı tekrar anahtarıyla istek hâlâ işleniyor. | Kısa beklemeden sonra aynı anahtar ve aynı gövdeyle yeniden deneyin. |
| 422 | `idempotency_key_reused` | Aynı tekrar anahtarı farklı gövdeyle kullanılmış. | Eski işi tekrarlıyorsanız eski gövdeyi; yeni işse yeni anahtarı kullanın. |
| 400 | `invalid_cursor` | İmleç kaynak, yetki veya süzgeçle uyuşmuyor. | Aynı süzgeç/kapsamı koruyun; kaybettiyseniz listeyi veya tutarlı ilk eşitlemeyi yeniden başlatın. |
| 422 | `invalid_id` | Kaynak kimliğinin öneki veya biçimi geçersiz. | Liste yanıtındaki doğru türde dış kimliği kullanın; iç sayısal kimlik göndermeyin. |

## Bütün hata kodları

Aşağıdaki katalog backend sözleşmesinden üretilir; uca özgü kodlar da buradadır.

| HTTP | code | Anlamı | Nasıl düzelir? |
| --- | --- | --- | --- |
| 409 | `amount_changed` | İade tutarı değişti; yeniden önizleyip onaylayın. | current_amount güncel TRY tutarıdır; önizlemeyi okuyup yeni anahtar ve expected_amount ile gönderin. |
| 403 | `bulk_access_changed` | İşin erişim kapsamı değişti. | İşin açıldığı bağlantı ve kaynak kapsamlarını kontrol edin. |
| 409 | `bulk_in_progress` | Bu işletmede bir toplu iş sürüyor. | Önce açık işin bitmesini bekleyin; sonra yeni tekrar anahtarı kullanın. |
| 403 | `business_scope_required` | Bu kayıt işletme genelindedir. | Bütün markalara yetkili bağlantı kullanın. |
| 422 | `category_cycle` | Kategori kendisinin veya alt kategorisinin altına taşınamaz. | Başka üst kategori seçin; yeni tekrar anahtarı kullanın. |
| 409 | `code_taken` | Stok kodu veya barkod başka bir kayıtta kullanılıyor. | Görünür existing_variant / existing_product kimliğini okuyun veya farklı kod seçin. |
| 409 | `conflict` | Sipariş veya ödeme bilgisi değişmiş ya da işlem mevcut duruma uygun değil. | Güncel siparişi okuyun, iş kuralını kontrol edip yeni tekrar anahtarıyla deneyin. |
| 409 | `coupon_code_taken` | Kupon kodu bu markada başka kuponda kullanılıyor. | Başka kod seçin veya mevcut kuponu güncelleyin; yeni tekrar anahtarı kullanın. |
| 409 | `coupon_restore_conflict` | Kupon arşivde değil. | Güncel kaydı okuyun. |
| 409 | `customer_anonymization_blocked` | Müşteri mevcut durumda anonimleştirilemiyor. Açık siparişlerini tamamlayın veya iptal edin. | Paneldeki anonimleştirme önkoşulunu giderip yeni tekrar anahtarıyla gönderin. |
| 409 | `customer_exists` | Bu iletişim bilgileriyle müşteri zaten var. | existing_customer kimliğini kullanın; değiştirmek için PATCH gönderin. |
| 409 | `customer_restore_conflict` | Müşteri geri getirilemedi. | Kartın arşiv durumunu ve üyelik bağını panelden kontrol edin; anonimleşmiş kart geri getirilemez. |
| 409 | `delivery_in_progress` | Bu adrese teslim sürüyor. | Teslimin tamamlanmasını bekleyip yeniden gönderin. |
| 409 | `document_already_reversed` | Bu stok belgesi zaten tersine çevrilmiş. | Güncel belgedeki reversed_by kaydını okuyun. |
| 403 | `document_forbidden` | Belgenin tüm satırları marka kapsamında değil. | İşletmenin tümüne yetkili stok bağlantısı kullanın. |
| 409 | `duplicate_external_reference` | Bu dış numarayla sipariş zaten açılmış. | existing_order içindeki ord_ kimliğini kullanın; ikinci sipariş açılmadı. |
| 422 | `duplicate_line` | Aynı sipariş satırı birden çok kez gönderilmiş. | Her lin_ kimliğini yalnız bir kez yazın. |
| 409 | `endpoint_closed` | Webhook adresi kapalı. | Yeni adres kaydı oluşturun ve imzalı denemeyi tamamlayın. |
| 409 | `endpoint_inactive` | Webhook adresi henüz etkin değil. | Önce imzalı deneme gönderip alıcıdan 2xx alın. |
| 403 | `export_access_changed` | Dosya oluşturulduktan sonra erişim kapsamı değişmiş. | Güncel izinlerle yeni dışa aktarma başlatın. |
| 409 | `export_in_progress` | Bu işletmede başka bir dosya hazırlanıyor. | Retry-After kadar bekleyin; mevcut hazırlama bitince yeni Idempotency-Key ile isteyin. |
| 409 | `export_not_ready` | Dosya henüz hazır değil. | Dışa aktarma durumunu okuyup completed olmasını bekleyin. |
| 409 | `external_reference_conflict` | Bu dış numarayla stok belgesi zaten açılmış. | Ağ tekrarında özgün Idempotency-Key değerini ve gövdeyi kullanın. |
| 410 | `file_expired` | Dosyanın 7 günlük erişim süresi dolmuş. | Yeni dışa aktarma başlatın; mevcut olay devam imleci kullanılabilir. |
| 503 | `file_unavailable` | Hazır dosyaya şu an erişilemiyor. | Retry-After kadar bekleyip indirmeyi yeniden deneyin. |
| 403 | `forbidden` | Mevcut ticari kural bu işlemi yapmanıza izin vermiyor. | Gerekli kapsamları ve siparişin durumunu kontrol edin. |
| 403 | `grant_mismatch` | Başka API bağlantısının webhook adresi istenmiş. | Yalnız kullandığınız Bearer anahtarının bağlantısını yönetin; grant alanını atlayabilirsiniz. |
| 409 | `idempotency_in_progress` | Aynı tekrar anahtarıyla istek hâlâ işleniyor. | Kısa beklemeden sonra aynı anahtar ve aynı gövdeyle yeniden deneyin. |
| 400 | `idempotency_key_required` | Tekrar anahtarı eksik. | Idempotency-Key başlığına yeni iş için benzersiz değer yazın. |
| 422 | `idempotency_key_reused` | Aynı tekrar anahtarı farklı gövdeyle kullanılmış. | Eski işi tekrarlıyorsanız eski gövdeyi; yeni işse yeni anahtarı kullanın. |
| 403 | `insufficient_scope` | Gerekli kapsam eksik. | İşletme sahibinden uç ve alt kaynakların okuma kapsamlarını isteyin. |
| 400 | `insufficient_stock` | Sipariş için yeterli stok yok. | Miktarı azaltın veya paneldeki bekleyen stok kuralını açıkça allow_waiting=true ile seçin. |
| 500 | `internal_error` | Sunucu isteği tamamlayamadı. | Güvenle tekrarlanabilen isteği artan beklemeyle deneyin; sürerse request_id ile destek alın. |
| 401 | `invalid_api_key` | Anahtar geçersiz, süresi dolmuş veya iptal edilmiş. | Panelde açık bağlantı oluşturun/döndürün; sunucu ortamındaki anahtarı güncelleyin. |
| 400 | `invalid_cursor` | İmleç kaynak, yetki veya süzgeçle uyuşmuyor. | Aynı süzgeç/kapsamı koruyun; kaybettiyseniz listeyi veya tutarlı ilk eşitlemeyi yeniden başlatın. |
| 422 | `invalid_date_range` | Zaman aralığının başlangıcı bitişten sonra. | Başlangıç ve bitiş sırasını düzeltin. |
| 422 | `invalid_datetime` | Zamanın saat dilimi eksik. | RFC 3339 değere Z veya +03:00 gibi saat dilimi ekleyin. |
| 422 | `invalid_event_types` | Olay türü geçersiz veya izinli tür yok. | Olay kataloğundan tür seçin ve kaynak kapsamını açın. |
| 422 | `invalid_grant` | Webhook yönetimi açık bağlantı bulunamadı. | Açık, webhooks:manage kapsamlı bağlantı kullanın. |
| 422 | `invalid_id` | Kaynak kimliğinin öneki veya biçimi geçersiz. | Liste yanıtındaki doğru türde dış kimliği kullanın; iç sayısal kimlik göndermeyin. |
| 400 | `invalid_if_match` | If-Match geçerli bir güçlü ETag değil. | GET kaynak yanıtındaki ETag değerini çift tırnaklarıyla aynen kullanın. |
| 422 | `invalid_include` | Genişletme adı geçersiz veya yineleniyor. | Yalnız ucun desteklediği include değerlerini birer kez gönderin. |
| 422 | `invalid_patch` | Düzeltilecek alan veya seçenek uygun değil. | Değişmeyecek alanı atlayın; seçeneğin sipariş satırındaki ürüne ait olduğunu ve alan kurallarını kontrol edin. |
| 422 | `invalid_range` | Zaman aralığının başlangıcı bitişten önce değil. | Başlangıç dahil, bitiş hariç olacak şekilde başlangıcı bitişten önce seçin. |
| 400 | `invalid_request` | İstek biçimi geçersiz. | Gövdeyi ve başlıkları kontrol edin; Idempotency-Key en çok 200 karakterdir. |
| 422 | `invalid_stock_operation` | Stok işlemi ürünün veya deponun kurallarına uygun değil. | Birimi, depo durumunu, sayılmayan stoğu ve belge türünü kontrol edin. |
| 422 | `invalid_store` | Marka bağlantının yetkisinde değil veya kapalı. | /me stores listesindeki bir markayı seçin. |
| 422 | `invalid_webhook_url` | Webhook adresi kabul edilmiyor. | Genel internete çözülen, kullanıcı bilgisi içermeyen HTTPS/443 adresi kullanın. |
| 409 | `invoice_already_cancelled` | Fatura zaten iptal edilmiş. | Güncel faturayı okuyun. |
| 409 | `invoice_billing_invalid` | Siparişin fatura bilgileri uygun değil. | Paneldeki açıklamaya göre fatura bilgilerini tamamlayın. |
| 409 | `invoice_cancel_running` | Fatura iptali sürüyor. | Süren çağrının bitmesini bekleyin. |
| 409 | `invoice_cancel_uncertain` | Fatura iptalinin sonucu belirsiz. | Yeni dış iptal gönderilmez; portalda doğrulayıp portal_done=true ile tamamlayın. |
| 409 | `invoice_connection_changed` | Fatura sağlayıcı bağlantısı değişti. | Önceki sağlayıcı hesabında faturayı kontrol edin. |
| 409 | `invoice_empty_order` | Siparişte ürün yok; fatura kesilemez. | Sipariş kalemlerini kontrol edin. |
| 409 | `invoice_exists` | Siparişin etkin faturası var. | Mevcut faturayı okuyun; hazırlanan fatura için yeni istek açmayın. |
| 409 | `invoice_not_allowed` | Fatura işlemi şu an yapılamıyor. | Açıklamadaki panel kuralını izleyin. |
| 409 | `invoice_not_connected` | Fatura sağlayıcısı bağlı değil. | İşletme > Entegrasyonlar bölümünden sağlayıcınızı bağlayın. |
| 409 | `invoice_not_ready` | Fatura belgesi henüz hazır değil. | Faturanın numarası kesinleşince yeniden deneyin. |
| 409 | `invoice_order_not_allowed` | Bu siparişe fatura kesilemez. | Siparişin iptal/iade durumunu kontrol edin. |
| 409 | `invoice_payment_required` | Ödeme gelince fatura kesilebilir. | Ödeme kaydını kontrol edin. |
| 409 | `invoice_portal_required` | Sağlayıcı portalından iptal gerekiyor. | Portalda tamamladıktan sonra portal_done=true gönderin. |
| 409 | `invoice_provider_auth` | Fatura sağlayıcısı bağlantı bilgilerini kabul etmedi. | İşletme > Entegrasyonlar bölümünden bağlantıyı düzeltin; aynı faturayı izleyin. |
| 409 | `invoice_provider_error` | Fatura sağlayıcısı işlemi tamamlayamadı. | Faturanın durumunu ve sağlayıcı portalını kontrol edin. |
| 400 | `invoice_seller_invalid` | İşletmenin vergi bilgileri eksik. | İşletme bilgilerini tamamlayın. |
| 409 | `invoice_zero_total` | Sipariş tutarı 0 TL; fatura kesilmez. | Sipariş tutarını kontrol edin. |
| 400 | `key_in_query` | Anahtar URL sorgusuna yazılmış. | Anahtarı yalnız Authorization: Bearer başlığında gönderin. |
| 401 | `live_key_in_sandbox` | Canlı anahtar deneme ortamında kullanılamaz. | Deneme panelinde ayrı bir spk_test_ anahtarı oluşturun. |
| 405 | `method_not_allowed` | Uç HTTP yöntemini desteklemiyor. | Başvuruda yazılı GET/POST/PATCH yöntemini kullanın. |
| 404 | `not_found` | Kayıt/uç yok veya anahtarın marka sınırında görünmüyor. | Kimlik önekini, markayı ve arşiv süzgecini kontrol edin. |
| 409 | `product_restore_conflict` | Ürün geri getirilemedi. | Arşiv durumunu ve stok kodu/barkod çakışmasını panelden kontrol edin. |
| 429 | `quote_rate_limited` | İşletmenin kargo fiyatı sorgulama sınırına ulaşıldı. | Retry-After saniye bekleyin; 60 saniyede 20 sorgu bütün bağlantı ve markalarda ortaktır. Gönderi açma bu sayaçtan etkilenmez. |
| 429 | `rate_limit_exceeded` | Okuma veya hatalı anahtar hız sınırına ulaşıldı. | Retry-After saniyesini bekleyin; artan bekleme ve rastgele gecikme kullanın. |
| 403 | `reference_namespace_forbidden` | Dış numaranın ad alanı başka bağlantıya ait. | namespace alanını atlayın veya /me içindeki grt_ kimliğini kullanın. |
| 409 | `refund_confirm` | Düzeltme müşteriye para döndürüyor; tutar teyidi gerekiyor. | İade tutarını kontrol edip refund_amount alanıyla ve yeni tekrar anahtarıyla gönderin; money_out:write gerekir. |
| 409 | `refund_distribution_confirm` | Kart ve elle ödeme dağılımı değişti. | Yeniden önizleyip refund_distribution alanını aynen ve yeni tekrar anahtarıyla gönderin. |
| 422 | `reserved_note` | Bu açıklama sistem işlemlerine ayrılmıştır. | İşlemi kendi sözcüklerinizle açıklayın; yeni tekrar anahtarı kullanın. |
| 409 | `return_not_requested` | Bu kayıt bir müşteri iade talebi değil. | Siparişin returns listesinden müşteri talebini seçin. |
| 412 | `revision_mismatch` | Kayıt siz okuduktan sonra değişmiş. | Güncel kaydı okuyun; düzeltmeyi yeniden değerlendirip yeni tekrar anahtarıyla gönderin. |
| 409 | `rotation_unavailable` | Adres kapalı veya önceki sır geçişi sürüyor. | Önceki geçişin bitmesini bekleyin; kapalı adres için yeni kayıt açın. |
| 503 | `service_unavailable` | Servis geçici olarak yoğun veya erişilemiyor. | Retry-After kadar bekleyip güvenle tekrarlanabilen isteği deneyin. |
| 409 | `shipment_label_not_ready` | Etiket hazır değil veya gönderi iptal edilmiş. | Gönderinin açılışının tamamlanmasını bekleyin. |
| 409 | `shipment_not_allowed` | Gönderinin veya siparişin durumu bu işleme uygun değil. | Güncel gönderiyi ve siparişi okuyun; bekleyen işlemin sonuçlanmasını izleyin. |
| 400 | `shipping_address_invalid` | Alıcı adresi eksik veya geçersiz. | Siparişin il, ilçe, mahalle ve açık adresini düzeltin; yeni tekrar anahtarı kullanın. |
| 400 | `shipping_balance_insufficient` | Kargo bakiyesi yetersiz. | BasitKargo bakiyesini yükleyin; yeni tekrar anahtarıyla deneyin. |
| 400 | `shipping_carrier_disabled` | Kargo firması kapalı veya seçilemez. | Fiyat yanıtındaki açık firma kodunu seçin. |
| 400 | `shipping_cod_unavailable` | Kapıda ödeme bu hesapta veya firmada kullanılamıyor. | BasitKargo kapıda ödeme ayarlarını ve siparişin ödeme yöntemini kontrol edin. |
| 409 | `shipping_not_connected` | BasitKargo hesabı bağlı değil. | İşletme ayarları > Kargo’dan hesabı bağlayın. |
| 502 | `shipping_provider_error` | Kargo etiketi alınamadı veya yanıtta SVG etiketi bulunamadı. | Bir süre sonra aynı gönderinin etiketini yeniden indirin. |
| 400 | `shipping_quote_unavailable` | Bu paket ve ödeme yöntemi için ücret bulunamadı. | Koli ölçülerini ve firma seçimini kontrol edin. |
| 429 | `shipping_rate_limited` | Kargo sağlayıcısının istek sınırına ulaşıldı. | Retry-After saniye bekleyin; gönderi açılışında aynı anahtarı koruyun. |
| 503 | `shipping_unavailable` | Kargo hizmetine şu an ulaşılamıyor. | Retry-After saniye bekleyin; aynı anahtar/gövdeyle tekrar edin. |
| 409 | `snapshot_publisher_changed` | Olay yayıncısının sürümü ilk görüntüyle uyuşmuyor. | Yeni tutarlı dışa aktarma ve onun resume_cursor değeriyle başlayın. |
| 409 | `status_mismatch` | Sipariş durumu expected_status ile uyuşmuyor. | Güncel durumu okuyup yeni tekrar anahtarıyla deneyin. |
| 409 | `stock_changed` | Sayım sırasında stok değişmiş. | Güncel depo miktarını okuyup expected alanını yenileyin; yeni tekrar anahtarı kullanın. |
| 403 | `store_forbidden` | Anahtar başka markaya yazamaz. | Anahtarın kendi markasını seçin; marka sınırı gövdeyle genişletilmez. |
| 422 | `store_required` | Çok markalı işletmede kaydın markası eksik. | /me yanıtındaki sto_ kimliğini store alanına yazın. |
| 409 | `taxonomy_name_conflict` | Aynı anda bu addan başka kayıt açıldı. | Güncel listeyi okuyun; yeni tekrar anahtarıyla yeniden deneyin. |
| 409 | `taxonomy_restore_conflict` | Kayıt arşivden geri getirilemedi. | Güncel arşiv durumunu kontrol edin. |
| 401 | `test_key_in_live` | Deneme anahtarı canlı ortamda kullanılamaz. | spk_test_ anahtarını https://api.sandbox.siparis.app/v1 adresinde kullanın. |
| 400 | `unsupported_api_version` | İstenen sürüm desteklenmiyor. | Siparis-Version başlığını v1 yapın veya kaldırın. |
| 422 | `validation_error` | İstek alanı veya değeri geçersiz. | errors içindeki field ve code değerlerine göre isteği düzeltin. |