Temeller
Hata kodları
Kararlı makine kodları, HTTP karşılıkları ve hangi hatada yeniden denenir.
Her hata kararlı bir makine kodu taşır: DOMAIN-ALAN-NNNN.
{ "error": { "code": "CORE-AUTH-0001", "message": "…", "hint": "…", "trace_id": "…" } }Dallanmayı codea yap. message kullanıcının diline göre çevrilir ve metin iyileştirildikçe değişir; code bir sözleşmedir ve değişmez.
Çekirdek kodları
| Kod | HTTP | Sınıf | Anlamı |
|---|---|---|---|
CORE-SYS-0001 | 500 | sunucu | Beklenmeyen iç hata. Idempotent işlemler geri çekilmeyle yeniden denenebilir. |
CORE-SYS-0002 | 503 | sunucu | Bir bağımlılık (DB/Redis/kuyruk) geçici olarak yok. Yeniden denenebilir. |
CORE-SYS-0003 | 504 | sunucu | Zaman aşımı. Yeniden denenebilir. |
CORE-SYS-0004 | 501 | sunucu | Uç/özellik yok. |
CORE-REQ-0001 | 400 | istemci | Bozuk istek (geçersiz JSON, eksik alan). |
CORE-REQ-0002 | 422 | istemci | Doğrulama başarısız; alan bazlı hatalar details[] içinde. |
CORE-REQ-0003 | 404 | istemci | Kaynak yok (ya da çalışma alanı kapsamı dışında). |
CORE-REQ-0004 | 409 | istemci | Durum çakışması (mükerrer, ön koşul, kullanımda). |
CORE-REQ-0005 | 409 | istemci | Idempotency anahtarı farklı bir gövdeyle kullanılmış. |
CORE-REQ-0006 | 413 | istemci | Gövde tavanı aşıldı. |
CORE-AUTH-0001 | 401 | istemci | Kimlik yok ya da geçersiz. |
CORE-AUTH-0002 | 403 | istemci | Kimlik geçerli, yetki yok. |
CORE-RATE-0001 | 429 | istemci | Hız sınırı; Retry-Afterı gözet. |
CORE-TENANT-0001 | 404 | istemci | Çalışma alanı çözülemedi. |
CORE-TENANT-0002 | 403 | istemci | Çalışma alanı askıya alınmış. |
CORE-TENANT-0003 | 400 | istemci | Kiracı kapsamlı bir uca kiracısız ulaşıldı. |
Sınıflar: istemci (4xx — isteği düzeltmelisin; olduğu gibi yeniden denenmez) · sunucu (5xx — geçici; idempotent istekler geri çekilmeyle denenebilir).
Modül kodları
Her modül kendi önekini kullanır: CRM-*, ERP-*, SHOP-*, B2B-*, ADS-*… Yapı aynıdır ve aynı sınıflandırma geçerlidir.
En sık karşılaşacağın modül kodu lisans kapısıdır:
{ "error": { "code": "CRM-LIC-0001", "message": "Bu modül aboneliğinde yok.",
"hint": "module_not_licensed" } }Sekiz modülün hepsi aynı 403'ü ve aynı hinti döner — entegrasyonun tek bir dalda karar verebilmesi için.
Public API kodları
/public/v1/... uçları farklı bir zarf ve kelime dağarcığı kullanır:
code | HTTP |
|---|---|
unauthorized | 401 |
forbidden | 403 |
not_found | 404 |
parameter_invalid | 400 |
conflict | 409 |
rate_limit_exceeded | 429 |
internal_error | 500 |
Yeniden deneme kuralı
| Durum | Yeniden dene? |
|---|---|
429 | Evet — Retry-After kadar bekledikten sonra |
500 · 502 · 503 · 504 | Evet — üstel geri çekilme + jitter |
408 (zaman aşımı) | Evet |
4xx (diğer) | Hayır — istek yanlış; tekrarı da yanlış olur |
Yeniden denediğin her yazma isteğinde Idempotency-Key kullan. Yoksa "belki ulaştı" durumundaki bir istek ikinci kaydı doğurur.