# Hatalar (/baslangic/hatalar)

Başarısız her istek bir HTTP durum kodu ve şu gövdeyi döner:

```json
{
  "hata": {
    "kod": "izin_yok",
    "mesaj": "Bu anahtarın \"siparis:yazma\" izni yok. Panelde Ayarlar → API anahtarları'ndan yeni anahtar oluşturun."
  }
}
```

- **`kod`** makine içindir: sabit, küçük harf, alt çizgili. Kodunda buna göre dallan.
- **`mesaj`** insan içindir: Türkçe, ne yapılacağını söyler. Metni değişebilir; koşul olarak kullanma.

## Kodlar [#kodlar]

| Durum | `kod` | Anlamı |
| --- | --- | --- |
| 400 | `gecersiz_json` | Gövde geçerli JSON değil |
| 400 | `gecersiz_tekrar_anahtari` | `Idempotency-Key` 1–255 karakter olmalı |
| 401 | `anahtar_yok` | `Authorization: Bearer …` başlığı yok ya da biçimi yanlış |
| 401 | `anahtar_gecersiz` | Anahtar geçersiz ya da iptal edilmiş |
| 403 | `izin_yok` | Anahtarda bu ucun izni yok |
| 403 | `magaza_donduruldu` | Mağaza dondurulmuş |
| 403 | `acik_anahtar_silemez` | Test anahtarıyla silme denendi |
| 404 | `bulunamadi` | Kayıt ya da uç yok |
| 409 | `tekrar_suruyor` | Aynı `Idempotency-Key` ile bir istek hâlâ işleniyor |
| 409 | `musteri_var` | Bu e-postayla müşteri zaten var |
| 409 | `depo_yok` | Verilen depo bu mağazada yok |
| 415 | `json_gerekli` | Gövdeli istekte `Content-Type: application/json` yok |
| 422 | `gecersiz_girdi` | Alan doğrulaması tutmadı; mesaj alanı söyler (`kalemler.0.miktar: …`) |
| 422 | `varyant_bulunamadi` | SKU ya da varyant kimliği yok |
| 422 | `tekrar_anahtari_kullanildi` | `Idempotency-Key` başka bir istekle kullanılmış |
| 422 | `gorsel_indirilemedi`, `gorsel_turu`, `gorsel_buyuk` | Verilen görsel adresi indirilemedi, türü ya da boyutu uygun değil |
| 429 | `istek_siniri` | [İstek sınırı](/baslangic/istek-siniri) aşıldı |
| 500 | `sunucu_hatasi` | Bizim tarafta bir sorun; tekrar dene, sürerse bize yaz |

## Tekrar denemeli mi? [#tekrar-denemeli-mi]

- **429 ve 5xx:** evet. 429'da `Retry-After` kadar bekle; 5xx'te artan aralıklarla (1, 2, 4… sn) dene.
  Yazan isteklerde [`Idempotency-Key`](/baslangic/tekrar-anahtari) gönderdiysen tekrar güvenlidir.
- **4xx (429 dışı):** hayır. İstek değişmeden tekrar edilirse aynı hatayı alır.