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):
{
"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ı 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. |