> ## Documentation Index
> Fetch the complete documentation index at: https://apidocs.noyax.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Hatalar

> HTTP durum kodları, hata yanıtının yapısı ve hataların ele alınması.

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ı](/tr/v1/guides/result-codes) sayfasındadır.

## Hata yanıtı

<ResponseField name="Success" type="boolean">Hatalarda `false`.</ResponseField>
<ResponseField name="ResultCode" type="string">Başarılı yanıtlarda `0000`. Hatalarda ilk hatanın kodu.</ResponseField>
<ResponseField name="Message" type="string">Tüm hata mesajları, boşlukla ayrılmış tek metin (İngilizce).</ResponseField>
<ResponseField name="Errors" type="array">Her hata için `Code` ve `Message`. Sadece hatalarda döner.</ResponseField>

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.

```json theme={null}
{
  "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." }
  ]
}
```

<Tip>
  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.
</Tip>

## 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](/tr/v1/guides/authentication) ve tekrar deneyin                        |
| `403 Forbidden`             | Anahtarın bu işlem için [yetkisi](/tr/v1/guides/permissions) yok                   | Yetki talep edin                                                                           |
| `404 Not Found`             | Kayıt yok, silinmiş ya da kullanıcı kaydı [göremiyor](/tr/v1/guides/sharing-codes) | ID'yi, şirketi ve kullanıcının paylaşım kodlarını kontrol edin                             |
| `429 Too Many Requests`     | [Günlük limit](/tr/v1/guides/rate-limits) 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:

<Steps>
  <Step title="Token (401)">Token var mı, imzası ve süresi geçerli mi?</Step>
  <Step title="Header'lar (400)">`X-UserID`, `X-CompanyID`, `X-PeriodID` geçerli mi, kullanıcı şirkete tanımlı mı?</Step>
  <Step title="Yetki (403)">Anahtarın modülde gereken okuma ya da yazma yetkisi var mı?</Step>
  <Step title="Günlük limit (429)">Bugünkü limit aşıldı mı?</Step>
  <Step title="Gövde biçimi (400)">JSON gövdesi okunabiliyor mu?</Step>
  <Step title="İş kuralları (400 / 404)">Alanlar geçerli mi, kayıt var ve görülebilir mi?</Step>
</Steps>

## 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:

```json theme={null}
{
  "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

```javascript theme={null}
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}`);
}
```

<Tip>
  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.
</Tip>