Hatalar ve istisnalar

Bu sayfa Cluster ERP'nin hata sınıflarını ve kodlarını ve sunucunun istisnaları HTTP yanıtlarına nasıl çevirdiğini listeler. core/errors.py, core/exceptions.py ve server/error_handler.py dosyalarını kapsar. Kodların istemcinin gördüğü biçimde nedenleriyle tam listesi API hataları sayfasındadır.

Kapsam ve kaynak¶

• Tanımlandığı yer: src/cluster_erp/core/errors.py (AppError, kod sabitleri, fabrikalar), src/cluster_erp/core/exceptions.py (platform istisnaları), src/cluster_erp/server/error_handler.py (install_error_handlers)
• Sayı: core/errors.py içinde NAME = "NAME" biçiminde 213 modül düzeyi dizgi sabiti (grep -c -E '^[A-Z_0-9]+ = "' ile sayıldı), 23 yorumlu grupta; 6 fabrika işlevi; core/exceptions.py içinde 7 istisna sınıfı (grep -c "^class" ile sayıldı)

Hata gövdesi¶

Ele alınan her hata _build_body ile kurulan bir JSON gövdesi döndürür (src/cluster_erp/server/error_handler.py:33-46):

{
 "error": {
 "code": "<CODE>",
 "message": "<developer message>",
 "trace_id": "<YYMMDD-NNN>",
 "details": {}
 }
}

details yalnızca boş değilse bulunur. Hata ayıklama kipinde ele alınmayan istisna işleyicisi debug_message ve exception_type ekler, eşlenmiş işleyiciler debug_message ekler (src/cluster_erp/server/error_handler.py:305-308, src/cluster_erp/server/error_handler.py:345-347). debug_message en fazla sürücü mesajının ilk satırını, 300 karaktere kısaltılmış olarak taşır; SQL metnini asla taşımaz (src/cluster_erp/server/error_handler.py:99-107).

İzleme kimlikleri¶

_next_trace_id, trace_sequence tablosunda günlük bir sayacı artırır ve YYMMDD-NNN döndürür. Veritabanına ulaşılamazsa monoton bir saatten alınan sekiz basamakla YYMMDD- döndürür (src/cluster_erp/server/error_handler.py:49-70). Tablo feefe25508db_add_trace_sequence_table.py göçünden gelir. İşleyiciler izleme kimliğini ve hata verisini request.state üzerinde saklar; etkinlik günlüğü ara katmanı bunları hata günlüğüne yazar (src/cluster_erp/server/error_handler.py:73-93, src/cluster_erp/server/middleware.py:638-659).

AppError¶

AppError(code, message, *, status_code=400, details=None), servislerin ve rotaların yükselttiği istisnadır (src/cluster_erp/core/errors.py:6-30). Kod makine tarafından okunur, istemci onu yerelleştirilmiş bir metne eşler; mesaj İngilizce bir geliştirici dizgisidir (src/cluster_erp/core/errors.py:7-16).

Kod grupları¶

Bazı modüller kendi dosyalarında ek kodlar tanımlar; örneğin CURRENCY_UNKNOWN (src/cluster_erp/core/currencies.py:27) ve UPLOAD_TYPE_REFUSED (src/cluster_erp/core/upload_policy.py:19). Bunlar yukarıda sayılmamıştır.

Fabrikalar¶

İstisna işleyicileri¶

install_error_handlers(app, debug) aşağıdaki işleyicileri kaydeder (src/cluster_erp/server/error_handler.py:200-398).

Ele alınmayan istisna işleyicisinin 503 yanıtı Retry-After: 2 başlığını taşır (src/cluster_erp/server/error_handler.py:309). Her eşlenmiş tür kendi işleyicisini alır; böylece onu sunucu hatası ara katmanı yerine Starlette'in istisna ara katmanı ele alır (src/cluster_erp/server/error_handler.py:312-318, src/cluster_erp/server/error_handler.py:394-398).

Platform istisnaları¶

core/exceptions.py içindeki bu sınıfları modül kaydı ve EventBus yükseltir. HTTP kodlarına eşlenmezler.

Kısıtlar ve doğrulama¶

• max_request_body_bytes değerinden büyük bir istek gövdesi, herhangi bir işleyici çalışmadan önce bir ara katman tarafından HTTP 413 ve REQUEST_TOO_LARGE koduyla reddedilir (src/cluster_erp/server/app.py:1396-1410). Bu kod core/errors.py içindeki sabitlerden biri değildir.
• RESOURCE_PROTECTED hatası 403 değil, HTTP 400 kullanır (src/cluster_erp/core/errors.py:379-385).

Tanıtılan terimler¶

İlgili sayfalar¶

• Platform çekirdeği
• API hataları
• İstek hattı ve ara katmanlar
• Logs

92f8051 numaralı commit ile 2026-11-13 tarihinde doğrulandı.