API Errors Reference

REST API v1'in dönebileceği tüm hata kodları, anlamları ve nasıl çözüleceğine dair pratik rehber. Tüm yanıtlar tutarlı zarf formatındadır.

Standart hata zarfı

{
  "error": {
    "code": "rate_limited",
    "message": "Dakika başına 100 istek limiti aşıldı.",
    "status": 429
  }
}

validation_failed ekstra olarak alan-bazlı detay döner:

{
  "error": { "code": "validation_failed", "message": "...", "status": 422 },
  "errors": {
    "email":      { "code": "invalid_email", "message": "email geçerli e-posta olmalı." },
    "department": { "code": "too_long",      "message": "department en fazla 50 karakter olmalı." }
  },
  "fields": ["email", "department"]
}

Transport / Auth hataları

İstek API katmanına ulaştığında ama resource'a varmadan önce dönen hatalar.

HTTP 401

unauthorized

İstekte Authorization: Bearer <api_key> header'ı yok.

Çözüm: Her isteğe API key header'ı ekleyin. Key'i panel'den /api_keys.php sayfasından üretebilirsiniz.

HTTP 401

invalid_key_format

Bearer token tdk_ ile başlamıyor veya 40 karakterden kısa.

Çözüm: Key'i baştan sonuna kopyalayıp Authorization: Bearer tdk_... şeklinde gönderin.

HTTP 401

invalid_key

API key veritabanında bulunamadı veya hash eşleşmedi.

Çözüm: Key'in panel'de hâlâ aktif olduğunu doğrulayın. Silinmiş key tekrar oluşturulamaz — yeni key üretin.

HTTP 401

key_revoked

Key admin tarafından iptal edilmiş.

Çözüm: Yeni bir key üretin ve eski entegrasyonu güncelleyin.

HTTP 403

tenant_suspended

Tenant aktif değil (deneme süresi dolmuş veya admin tarafından askıya alınmış).

Çözüm: Üst yönetimle iletişime geçin veya aboneliği yenileyin.

HTTP 503

tenant_unavailable

Tenant DB'sine bağlanılamadı.

Çözüm: Geçici altyapı sorunu olabilir. Retry-After header'ına saygı duyarak tekrar deneyin. Süreklilik arz ederse durum sayfasına bakın.

HTTP 403

forbidden

Key'in bu endpoint veya HTTP metodu için scope'u yok.

Çözüm: Key oluştururken doğru scope'u (örn. customers:write) seçtiğinizden emin olun.

HTTP 429

rate_limited

Dakikada 100 istek sınırı aşıldı.

Çözüm: Retry-After: 60 header'ı kadar bekleyin. Burst yerine sabit hızlı istek dağıtın; X-RateLimit-Remaining ile takip edin.

HTTP 405

method_not_allowed

Endpoint için bu HTTP metodu desteklenmiyor.

Çözüm: Allow header'ında dönen metotlardan birini kullanın. OpenAPI referansına bakın.

HTTP 400

invalid_json

Request body geçerli JSON değil.

Çözüm: Content-Type: application/json header'ı + valid JSON gövde gönderin. Trailing comma yok, double quote zorunlu.

Resource hataları

Endpoint resource'una eriştikten sonra döndürülen hatalar.

HTTP 404

not_found

Belirtilen ID ile kayıt bulunamadı.

Çözüm: ID'nin doğru olduğunu ve aktif tenant'a ait olduğunu doğrulayın. Silinen kayıt 404 döner.

HTTP 400

missing_id

PUT/DELETE isteği için query string'de ?id=N yok.

Çözüm: Hedef kaydın ID'sini query parametresi olarak ekleyin.

HTTP 400

no_fields

Güncellenecek hiçbir geçerli alan body'de yok.

Çözüm: PUT body'sine en az bir güncellenebilir alan ekleyin. Salt-okunur alanlar (id, created_at) yok sayılır.

HTTP 400

invalid_request

Genel istek hatası — eksik veya geçersiz parametre.

Çözüm: Hata mesajındaki ipucunu okuyun. OpenAPI'de ilgili endpoint'in zorunlu alanlarını kontrol edin.

HTTP 422

validation_failed

Alan-bazlı validation hataları (zorunlu, format, enum, uzunluk).

Çözüm: Response'taki errors nesnesinde her alan için ayrı code + message dönülür. Hepsini düzeltip yeniden gönderin.

HTTP 422

invalid_customer

Belirtilen customer_id mevcut değil.

Çözüm: Önce şubeyi (POST /customers.php) oluşturun, sonra personel ekleyin.

HTTP 422

invalid_employee

Belirtilen employee_id mevcut değil.

Çözüm: Donanımı bir personele atamadan önce personel kaydının var olduğundan emin olun.

HTTP 409

conflict

Silme talebi foreign key kısıtı yüzünden reddedildi (bağlı kayıtlar var).

Çözüm: Önce alt kayıtları (personel, donanım, vb.) silin veya başka kayda taşıyın. details alanında DB hata mesajı dönülür.

Validation alan kodları

validation_failed içinde her alan için döndürülen alt kodlar:

Code	Anlamı
`required`	Zorunlu alan boş.
`invalid_email`	E-posta formatı geçersiz.
`invalid_int`	Tamsayı bekleniyordu.
`invalid_date`	YYYY-MM-DD formatında olmalı.
`invalid_bool`	Boolean (true/false, 1/0) bekleniyordu.
`too_long`	Maksimum karakter sayısı aşıldı.
`too_short`	Minimum karakter sayısının altında.
`not_in_list`	Değer izin verilen enum'dan biri değil.

Rate limit header'ları

Tüm başarılı yanıtlarda + rate_limited hatasında dönen üç header:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1718983261
Retry-After: 60   # sadece 429'da

Üretim entegrasyonları Remaining'i izleyip, Reset epoch'una kadar burst yapmaktan kaçınmalı.

Idempotency

POST/PUT/DELETE isteklerine Idempotency-Key: <uuid> ekleyin. Aynı key ile gelen ikinci istek ilk yanıtın aynısını döner (24 saatlik pencere) — network retry'larda duplicate kayıt riski olmaz.

Kaynak: api/v1/_bootstrap.php (transport) + her endpoint dosyası (resource). Yeni error code eklendiğinde bu sayfa da güncellenir. Hata kodu listesi OpenAPI spec'inde de bulunur.