REST API
Hatalar
HTTP durum kodları, makinece okunur hata kodları ve hatalara eşlik eden ek alanlar.
Başarısız bir istekte yanıt gövdesi şu biçimdedir:
{
"ok": false,
"error": "similar",
"message": "Benzer adlı firma var — mevcut kaydı seçin ya da confirm_new=1 ile yeni açın.",
"similar": [ { "id": 7, "name": "Alize Paketleme San. ve Tic. A.Ş.", "…": "…" } ]
}errormakinece okunur, değişmez bir koddur — kodunuzda buna göre dallanın.messagekullanıcıya gösterilebilecek Türkçe açıklamadır; metni değişebilir, ayrıştırmayın.- Bazı hatalar ek alan taşır:
similar,customer,gate_problems,module,state,otp.
Hata kodları
| Kod | HTTP | Anlamı |
|---|---|---|
unauthorized |
401 | Belirteç yok, geçersiz, süresi dolmuş ya da iptal edilmiş. |
credentials |
401 | Kullanıcı adı veya şifre hatalı. |
otp_required |
401 | İki adımlı doğrulama kodu gerekli (otp). |
otp_invalid |
401 | Doğrulama kodu hatalı ya da süresi geçmiş. |
forbidden |
403 | Kaydı görme / düzenleme yetkiniz yok. |
insufficient_scope |
403 | OAuth belirtecinde crm.write yok. |
module |
403 | Modül lisansta ya da kullanıcının izinlerinde kapalı. |
disabled |
403 | Yönetici bu özelliği çalışma alanında kapattı (ör. dijital kartvizitler, arayan kimliği). |
license |
403 | Lisans süresi doldu — yalnız yönetici erişebilir. |
ip |
403 | Bu ağdan erişim izni yok (IP kısıtı). |
not_found |
404 | Kayıt bulunamadı. |
invalid |
400 | Eksik ya da geçersiz alan (message ayrıntıyı verir). |
bad_request |
400 | v91: geçersiz sorgu parametresi (ör. bilinmeyen group; message geçerli değerleri sayar). |
send |
400 | E-posta gönderilemedi (hesap bağlı değil, alıcı geçersiz…). |
exists |
409 | Bu adla firma var (customer alanında döner). |
similar |
409 | Benzer adlı firmalar var (similar); confirm_new: true ile yine açılır. |
gate |
409 | Aşama kapısı sağlanmadı (gate_problems). |
geo_required |
400 | v66: yüz yüze ziyaret konumla kaydedilir — geo_lat / geo_lng ya da geo_note (neden) gönderin; reasons seçenekleri verir. |
locked |
429 | Çok fazla hatalı giriş — 60 sn bekleyin. |
rate_limited |
429 | Dakikalık istek sınırı aşıldı (Retry-After). |
limit |
429 | Kullanıcı başına saatlik soru sınırı (40) doldu. |
erp |
400 | ERP işlemi yapılamadı (message: sipariş bağlantısı yok, cari eşleşmedi, ürünün ERP kodu yok…). |
stock |
400 | Stok okunamadı (ürün ERP stok kartıyla eşleşmedi ya da ERP yanıt vermedi). |
too_many |
413 | Tek istekte en çok 2.000 kayıt. |
dial |
400 | v67: santralden arama başlatılamadı (message: dahili eşlenmemiş, numara geçersiz, santral yanıtı). |
sms |
400 | v67: SMS gönderilemedi (message: bağlantı yok, ret listesinde, ticari ileti satırı yok, sağlayıcı hatası). |
confirm |
409 | v67: onay gerekiyor (need_confirm: true) — bilgilendirme metninde kampanya sözcüğü ya da ret listesindeki numara; confirm: 1 ile yeniden gönderin. |
HTTP durum kodları
| Kod | Anlamı |
|---|---|
200 |
Başarılı. |
201 |
Oluşturuldu (OAuth istemci kaydı, SCIM kullanıcı açma). |
204 |
İçeriksiz başarı (SCIM kullanıcı kapatma). |
400 |
Eksik / geçersiz alan. |
401 |
Kimlik doğrulanamadı — belirteci yenileyin ya da yeniden giriş yapın. |
403 |
Yetki yok — rol, modül, kapsam, lisans ya da IP. |
404 |
Kayıt yok ya da görme yetkiniz dışında. |
405 |
Yöntem desteklenmiyor (ör. MCP ucuna GET). |
409 |
İş kuralı çakışması — mükerrer firma, aşama kapısı. |
429 |
Hız sınırı — Retry-After kadar bekleyin. |
500 |
Sunucu hatası. Tekrarlanıyorsa isteği ve zamanı info@solk.app'e iletin. |
Örnek: mükerrer firma
r = s.post(f"{BASE}/api/v1/customers", json={"name": "Alize Ambalaj"})
j = r.json()
if r.status_code == 409 and j["error"] == "exists":
firma = j["customer"] # zaten var — onu kullan
elif r.status_code == 409 and j["error"] == "similar":
adaylar = j["similar"] # kullanıcıya seçtir ya da:
j = s.post(f"{BASE}/api/v1/customers", json={"name": "Alize Ambalaj", "confirm_new": True}).json()Örnek: aşama kapısı
r = s.post(f"{BASE}/api/v1/opportunities/{oid}/stage", json={"stage": "Viable"})
if r.status_code == 409 and r.json()["error"] == "gate":
for sorun in r.json()["gate_problems"]:
print("Eksik:", sorun)