T-SOFT/Admin API/Hatalar

Hatalar

Hatalar JSON:API biçiminde, kök seviyedeki errors dizisinde döner. Her eleman status, title ve çoğu zaman detail taşır; hatanın kaynağı istek gövdesindeyse source.pointer, sorgu parametresindeyse source.parameter alanı eklenir.

{
  "jsonapi": { "version": "1.0" },
  "errors": [
    {
      "status": "422",
      "title": "Unprocessable Entity",
      "detail": "The warehouse id field is required.",
      "source": { "pointer": "/warehouseId" }
    }
  ]
}

Tek yanıtta birden fazla hata dönebilir; kullanıcıya göstermeden önce hepsini işleyin.

Durum kodları

Durum	Anlamı	Ne yapmalı
`400`	Geçersiz sorgu parametresi (izin verilmeyen filtre, `page[size]` > 100, eksik zorunlu filtre)	`source.parameter` alanındaki parametreyi düzeltin
`401`	Token yok, geçersiz, süresi dolmuş ya da başka bir mağazaya ait	Yeni token alın; yine `401` alırsanız uygulama kaldırılmış olabilir
`403`	Token'da bu ucun kapsamı yok	`detail` alanındaki izni Kapsamlar listesinden bulup kaydınıza ekletin
`404`	Kayıt yok; `code` `api_version_unsupported` ise adresteki sürüm yok	Yeniden denemeyin; sürüm hatasında Sürümler sayfasındaki güncel sürümü kullanın
`406`	`Accept` başlığı `application/vnd.api+json` değil	Başlığı düzeltin
`409`	Kayıt siz okuduktan sonra değişti (örn. sipariş durumunda `currentStatusId` tutmadı)	Kaydı yeniden okuyup karar verin
`410`	`api_version_retired`: adresteki sürümün desteği bitti	Yeni sürüme geçin (Sürümler)
`415`	Yazma isteğinde `Content-Type` `application/vnd.api+json` değil	Başlığı düzeltin
`422`	Gövde doğrulamadan geçmedi	`source.pointer` alanındaki değeri düzeltin
`429`	İstek sınırı aşıldı	`Retry-After` başlığındaki süre kadar bekleyin
`5xx`	Sunucu tarafı hata	Artan aralıklarla yeniden deneyin

Örnekler

Geçersiz filtre:

{
  "errors": [
    {
      "status": "400",
      "title": "Invalid Query Parameter",
      "detail": "Filter parameter nope is not allowed.",
      "source": { "parameter": "filter" }
    }
  ]
}

Eksik kapsam (detail eksik iznin Türkçe adıdır):

{
  "errors": [
    { "status": "403", "title": "Forbidden", "detail": "Siparişleri Görüntüle" }
  ]
}

Yeniden deneme

Yalnız 429 ve 5xx yanıtlarını yeniden deneyin. 4xx hataları isteğin kendisinden kaynaklanır; aynı isteği tekrar göndermek sonucu değiştirmez.

Admin API idempotency anahtarı desteklemez. Ağ kesintisinden sonra bir yazma isteğini tekrarlamadan önce kaydın son halini okuyun. Örneğin stok ayarlamak (warehouse-stocks/-actions/set) mutlak değer yazdığı için güvenle tekrarlanabilir; sipariş durumunu değiştirmeden önce siparişin güncel orderStatus değerine bakın.