Hata yanıtları

​

Hata zarfı

{
  "success": false,
  "error_code": "RESOURCE_NOT_FOUND",
  "message": "İstenen kaynak bulunamadı.",
  "meta": { "timezone": "Europe/Istanbul" }
}

​

Doğrulama hataları

{
  "success": false,
  "error_code": "VALIDATION_FAILED",
  "message": "Gönderilen veriler geçersiz.",
  "errors": {
    "name": ["İsim alanı zorunludur."],
    "phone_number": ["Telefon alanı zorunludur."]
  },
  "meta": { "timezone": "Europe/Istanbul" }
}

• Anahtarlar istek gövdesindeki alan adlarıdır. Bir alanın birden fazla hatası olabilir; değer her zaman bir dizidir.
• İç içe alanlar nokta ile yazılır: treatment_session_plans.0.sessions.0.scheduled_at. Sayı, dizideki sıra numarasıdır (0’dan başlar).
• Türkçe yanıtlarda alan mesajları Türkçedir ve alan adı Türkçe karşılığıyla geçer (örneğin name için İsim, phone_number için Telefon). İngilizce yanıtlarda standart doğrulama metinleri gelir.
• Bazı iş kuralı hataları da errors taşır ama kendi kodunu korur. Örneğin Telegram bağlantı hataları errors.bot_token ile gelir ve VALIDATION_FAILED değildir. Bu yüzden önce error_code değerine bakın.

​

HTTP durum kodları

• 403 ve 404 farkı. Kliniğinize ait olmayan ya da görünürlük kapsamınızın dışındaki bir kayıt için 403 değil 404 RESOURCE_NOT_FOUND alırsınız. Bu, kaydın var olup olmadığının sızmaması içindir. Görünürlük kuralları için İzinler ve görünürlük sayfasına bakın. İstisna: LEAD_NOT_ASSIGNED ve CONVERSATION_NOT_ASSIGNED 403 döner ve data.assigned_user ({id, name} ya da null) içerir. Böylece kaydın kime atandığını kullanıcıya gösterebilirsiniz.
• 403 ve scope. Token’ınızda gerekli scope yoksa 403 FORBIDDEN döner ve message her zaman İngilizce Invalid scope(s) provided. olur. Token’ın scope’u sonradan artmaz; uygulamanızın isteyeceği scope’ları Scope’lar sayfasından kontrol edip yeniden yetkilendirme yapın.
• 402 ve 428. 402 yanıtında data abonelik bilgisini (SUBSCRIPTION_REQUIRED) ya da proforma_invoice_id ve due_date alanlarını (ACCESS_RESTRICTED_BY_OVERDUE_PAYMENT) taşır. 428 yanıtında data.next_step kurulumun sıradaki adımını verir (örneğin clinic_info). Ayrıntılar için Erişim kilitleri sayfasına bakın.
• 429. Oran sınırı katmanından gelen yanıt Retry-After (saniye) ve X-RateLimit-Reset başlıklarını taşır; klinik oluşturma gibi servis düzeyindeki 429 yanıtlarında Retry-After yoktur. Bu başlıklar CORS ile açılmadığı için başka bir kökenden çalışan tarayıcı JavaScript’i onları okuyamaz; orada beklemeyi sabit bir süreyle ya da üstel artışla yapın. Sınırlar için Oran sınırları sayfasına bakın.
• 405. Yanıtta Allow başlığı desteklenen metotları listeler. 404 ve 405 mesajları yönlendirme düzeyinde oluştuğu için her zaman İngilizcedir.
• 409 ve 422 ayrımı. Çakışma durumları (örneğin zaten iptal edilmiş bir randevuyu iptal etmek) 409 döner. Çoğu iş kuralı hatası ise 422 ve kendi error_code değeriyle gelir; kodu belirtilmeyen iş kuralı hataları 422 varsayılır.

​

Hata koduna göre işlem yapma

async function flextell(path, options = {}) {
  const res = await fetch(`https://app.flextell.ai/api/v1${path}`, {
    ...options,
    headers: {
      Authorization: `Bearer ${accessToken}`,
      "X-Tenant": tenantId,
      Accept: "application/json",
      ...options.headers,
    },
  });

  if (res.ok) return res.json();

  const err = await res.json();

  switch (err.error_code) {
    case "UNAUTHENTICATED":
      // token'ı yenileyin, isteği bir kez tekrarlayın
      break;
    case "VALIDATION_FAILED":
      // err.errors: { alan: ["mesaj", ...] }
      throw Object.assign(new Error("Doğrulama hatası"), { fields: err.errors });
    case "TOO_MANY_REQUESTS": {
      const wait = Number(res.headers.get("Retry-After") ?? 1);
      await new Promise((r) => setTimeout(r, wait * 1000));
      return flextell(path, options);
    }
    default:
      throw Object.assign(new Error(err.message), { code: err.error_code, data: err.data });
  }
}

# X-Tenant başlığı olmadan klinik bağlamındaki bir endpoint'i çağırın
curl -i "https://app.flextell.ai/api/v1/tags" \
  -H "Authorization: Bearer <access_token>" \
  -H "Accept: application/json"
# 400 {"success":false,"error_code":"TENANT_HEADER_REQUIRED","message":"X-Tenant başlığı zorunludur."}

​

Hata önceliği

• Geçersiz JSON gönderen bir istemci, token’ı geçerli olsa da olmasa da 400 alır. Önce gövdeyi düzeltin.
• Genel oran sınırı kimlik doğrulamadan sonra sayılır; geçersiz token ile yapılan istekler bu sınıra yazılmaz.
• Doğrulama hatası (422) görmeniz, yetki ve kilit kontrollerinin geçildiği anlamına gelir.
• Abonelik ya da kurulum kilidi, alan doğrulamasından önce uygulandığı için bu durumlarda eksik alan hatası değil 402 ya da 428 alırsınız. Faturalama ile ilgili bazı endpoint’ler 402 kilidinde de açık kalır; ayrıntı Erişim kilitleri sayfasındadır.
• Hiçbir ayrıntı yanıta sızmaz: beklenmeyen bir istisna her zaman 500 SERVER_ERROR ve genel bir mesajla döner.

​

İlgili sayfalar