Hatalar her zaman aynı zarfta döner — meta bloğu başarılı yanıtlarla aynı şekilde request_id/timestamp içerir:
{
"success": false,
"error": { "code": "insufficient_scope", "message": "...", "fields": {} },
"meta": { "request_id": "req_...", "timestamp": "2026-08-02T10:00:00+00:00", "api_version": "v1" }
}error.fields yalnızca doğrulama (validation) hatalarında dolu gelir — alan bazlı hata mesajlarını içerir. Şu an gerçek yazma uç noktası olmadığı için bu alan pratikte henüz kullanılmıyor; yol haritası için bkz. Idempotency.
| HTTP | Kod | Anlamı |
|---|---|---|
| 401 | missing_api_key | Authorization/X-Api-Key header'ı gönderilmedi. |
| 401 | invalid_api_key | Key veritabanında bulunamadı. |
| 401 | key_revoked | Key iptal edilmiş ya da askıya alınmış. |
| 401 | key_expired | Key'in son kullanma tarihi geçmiş. |
| 403 | tenant_api_disabled | Süper Admin, galeriniz için tüm API erişimini kapatmış. |
| 403 | insufficient_scope | Key, bu uç nokta için gereken kapsama sahip değil. |
| 403 | endpoint_disabled | Bu uç nokta Süper Admin tarafından geçici olarak devre dışı bırakılmış. |
| 404 | not_found | Bilinmeyen uç nokta ya da kayıt bulunamadı. |
| 405 | method_not_allowed | Uç nokta bu HTTP metodunu desteklemiyor. |
| 429 | rate_limit_exceeded | Dakikalık istek limiti aşıldı — bkz. Hız Sınırları. |
| 500 | internal_error | Sunucu tarafında beklenmeyen bir hata oluştu. |
| 501 | not_implemented | Uç nokta katalogda dokümante edilmiş ama henüz aktif değil — bkz. Yol Haritası. |
Güvenlik amacıyla, bir API key ilk kez kullanıldığında galeriniz otomatik olarak Süper Admin'in izleme listesine eklenir ve Süper Admin'e e-posta ile bilgi verilir. Bu normal bir güvenlik önlemidir, isteğinizi engellemez.