Hatalar

Her yanıt sonucu iki katmanda bildirir:

HTTP durum kodu hatanın türünü söyler: istek hatalı mı (400), yetki mi yok (403), kayıt mı yok (404)?
ResultCode hatanın tam olarak ne olduğunu söyler: ör. 1002 cari kodu zaten kullanılıyor. Tüm kodlar Sonuç kodları sayfasındadır.

Hata yanıtı

boolean

Hatalarda false.

string

Başarılı yanıtlarda 0000. Hatalarda ilk hatanın kodu.

string

Tüm hata mesajları, boşlukla ayrılmış tek metin (İngilizce).

array

Her hata için Code ve Message. Sadece hatalarda döner.

Bir istekte birden fazla doğrulama hatası varsa hepsi tek yanıtta döner. Bu durumda ResultCode ilk hatanın kodudur; belirli bir hatayı ararken Errors listesine bakın.

{
  "Success": false,
  "ResultCode": "1006",
  "Message": "TaxNumber must contain only digits and be 10 (VKN) or 11 (TCKN) characters long. DiscountRate must be between 0 and 100.",
  "Errors": [
    { "Code": "1006", "Message": "TaxNumber must contain only digits and be 10 (VKN) or 11 (TCKN) characters long." },
    { "Code": "1008", "Message": "DiscountRate must be between 0 and 100." }
  ]
}

Entegrasyon mantığınızı Message metnine değil Code değerine dayandırın. Mesaj metinleri iyileştirilebilir, kodların anlamı ise değişmez.

HTTP durum kodları

Kod	Anlamı	Ne yapmalı?
`200 OK`	İstek başarılı
`201 Created`	Kayıt oluşturuldu. `Location` header’ı yeni kaydın adresini içerir
`204 No Content`	Silme başarılı, gövde yok
`400 Bad Request`	Header ya da gövde hatalı, iş kuralı ihlali	`Errors` listesini okuyup isteği düzeltin. Aynı isteği tekrar göndermek sonucu değiştirmez
`401 Unauthorized`	Token yok, geçersiz ya da süresi dolmuş	Token’ı yenileyin ve tekrar deneyin
`403 Forbidden`	Anahtarın bu işlem için yetkisi yok	Yetki talep edin
`404 Not Found`	Kayıt yok, silinmiş ya da kullanıcı kaydı göremiyor	ID’yi, şirketi ve kullanıcının paylaşım kodlarını kontrol edin
`429 Too Many Requests`	Günlük limit doldu	Ertesi gün tekrar deneyin
`500 Internal Server Error`	Beklenmeyen sunucu hatası (`0001`)	Bir süre sonra tekrar deneyin. Devam ederse destek ekibine bildirin

Kontrol sırası

Bir istekte farklı aşamalarda sorun varsa ilk aşamanın hataları döner. Kontroller şu sırayla yapılır:

Token (401)

Token var mı, imzası ve süresi geçerli mi?

Header'lar (400)

X-UserID, X-CompanyID, X-PeriodID geçerli mi, kullanıcı şirkete tanımlı mı?

Yetki (403)

Anahtarın modülde gereken okuma ya da yazma yetkisi var mı?

Günlük limit (429)

Bugünkü limit aşıldı mı?

Gövde biçimi (400)

JSON gövdesi okunabiliyor mu?

İş kuralları (400 / 404)

Alanlar geçerli mi, kayıt var ve görülebilir mi?

Gövde biçim hataları

JSON gövdesi okunamıyorsa (bozuk JSON, GUID alanına geçersiz değer, sayı alanına metin gibi) 400 ve 0002 kodu döner. Mesaj, hatalı alanın JSON yolunu içerir:

{
  "Success": false,
  "ResultCode": "0002",
  "Message": "$.DistrictId: The JSON value could not be converted to System.Nullable`1[System.Guid]. Path: $.DistrictId | LineNumber: 3 | BytePositionInLine: 26.",
  "Errors": [
    {
      "Code": "0002",
      "Message": "$.DistrictId: The JSON value could not be converted to System.Nullable`1[System.Guid]. Path: $.DistrictId | LineNumber: 3 | BytePositionInLine: 26."
    }
  ]
}

Hataları ele almak

const response = await fetch(url, options);

if (response.status === 401) {
  // Token'ı yenileyip isteği bir kez tekrarlayın
}

const body = response.status === 204 ? null : await response.json();

if (!body?.Success && response.status !== 204) {
  const codes = body.Errors.map((e) => e.Code);

  if (codes.includes("1002")) {
    // Cari kodu zaten kullanılıyor: mevcut cariyi bulup güncelleyin
  }

  throw new Error(`Noyax API ${response.status} [${body.ResultCode}]: ${body.Message}`);
}

Yalnızca 401 (token yenileme sonrası), 429 (ertesi gün) ve 500 yanıtlarını tekrar deneyin. 400, 403 ve 404 yanıtları istek değişmeden tekrarlandığında aynı sonucu verir.

Başlarken

Temel kavramlar

Modüller

Sürüm notları

Hata yanıtı

HTTP durum kodları

Kontrol sırası

Gövde biçim hataları

Hataları ele almak

​Hata yanıtı

​HTTP durum kodları

​Kontrol sırası

​Gövde biçim hataları

​Hataları ele almak

Hata yanıtı

HTTP durum kodları

Kontrol sırası

Gövde biçim hataları

Hataları ele almak