Hata ve Yanıt Kodları

Discuse API sorunları iki şekilde bildirir: message içeren bir HTTP hata durumu ya da alanları ne olduğunu anlatan normal bir 200 yanıtı. Bu sayfada, bunları doğru şekilde ele alabilmeniz için tüm durumlar listelenir — ayrıca kullanıcıların sıkça takıldığı bir noktayı açıklar: faturalandırma kotasının tükenmesi bir HTTP hatası değildir.

API hangi HTTP durumlarını döndürür?

Durum	Ne zaman	Ne yapmalı
200	Başarılı — "kota tükendi" durumu da buna dahildir	Yanıt gövdesini inceleyin; 200 her zaman her şey yolunda demek değildir (aşağıya bakın)
400	İstek doğrulaması başarısız oldu — boş içerik, 10.000 karakterden uzun text veya çok fazla medya URL’si	İsteği düzeltin; aynı şekilde yeniden denemeyin
401	API anahtarı eksik veya geçersiz	X-API-Key başlığını kontrol edin; aynı şekilde yeniden denemeyin
429	Anahtar için hız sınırı aşıldı	Bekleyin ve bir dakikalık pencere dolduktan sonra yeniden deneyin
500	Alt sistem/iç hata	Geri çekilme stratejisiyle yeniden deneyin

2xx olmayan tüm yanıtlarda message değerini okuyun. Kimlik doğrulama hataları 401, hız sınırı hataları 429, istek doğrulama hataları ise 400 döndürür; 5xx durumlarını geçici kabul edin ve geri çekilme stratejisiyle yeniden deneyin.

"Kota tükendi" neden hata değil de 200?

Bir proje aylık API isteği hakkını tükettiğinde, POST /api/v2/check yine de 200 döndürür — içerik ihlalsiz gibi değerlendirilir, kotanın tükendiğini açıklayan bir message ve sıfır kalan hakkı gösteren bir usage nesnesi gelir:

{
  "has_violations": false,
  "message": "API quota exceeded. Current: 10000, Limit: 10000",
  "usage": {
    "api_requests_used": 10000,
    "api_requests_limit": 10000,
    "api_requests_remaining": 0
  }
}

Bu bilinçli bir tercihtir: kotanın bitmesi, sunucu hatası gibi görünmemeli veya işlem hattınızı bir istisnayla durdurmamalıdır. Durum koduna güvenmek yerine usage.api_requests_remaining değerini (ve message alanını) kontrol edin. Bir 200 yanıtında varsayılan olarak işleme izin verirseniz, tükenmiş kota içeriğin kontrol edilmeden sessizce geçmesine yol açar — bu yüzden bu alanlara göre açıkça dallanma yapın.

Başarılı bir yanıtı nasıl okumalıyım?

/api/v2/check üzerinden gelen bir 200 yanıtı her zaman has_violations ve cached alanlarını içerir; geri kalanı isteğe bağlıdır:

Alan	Tür	Anlamı
has_violations	boolean	Etkin kontrollerden herhangi biri içeriği işaretlediyse True
cached	boolean	Yakın tarihli aynı istek önbelleğinden sunulduysa True
message	string	Kota tükenmesi durumunda (ve benzeri hata olmayan bildirimlerde) bulunur
request_id	string	Gönderdiyseniz size geri yansıtılır
processing_time_ms	number	Proje için zamanlama etkinse bulunur
usage	object	api_requests_used, api_requests_limit, api_requests_remaining
results	object	Kontrol bazında ayrıntı (spamfinder, sentiment, images, …) ve üst düzey hits bayrağı

Genel karar için has_violations alanına bakın, ardından hangi kontrolün tetiklendiğini görmek için results.<check>.hit içine inin.

Önbellekleme yanıtları nasıl etkiler?

Aynı proje için yapılan özdeş istekler tekilleştirilir: tekrar eden bir istek, aynı sonuçla birlikte cached: true döndürür. Önbellekleme proje bazındadır. Dikkat: önbellekten gelen bir istek yine de API isteği kotanızdan düşer — kotadan değil, işlem süresinden tasarruf sağlar.

Kendi eşleştirmeniz için bir isteğe request_id ekleyebilirsiniz; bu değer yanıtta size geri yansıtılır.

Minimal ve doğru bir istemci

async function check(content, settings) {
  const response = await fetch('https://api.discuse.com/api/v2/check', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': process.env.DISCUSE_API_KEY
    },
    body: JSON.stringify({ content, settings })
  });

  // 400: bad request — fix it, don't retry. 5xx: transient/auth/rate-limit — retry with backoff.
  if (response.status === 400) {
    throw new Error('Invalid request: ' + (await response.text()));
  }
  if (!response.ok) {
    throw new Error(`Discuse error ${response.status}`); // retry upstream with backoff
  }

  const data = await response.json();

  // Quota exhausted is a 200 — never treat it as "checked and clean".
  if (data.usage && data.usage.api_requests_remaining === 0 && data.message) {
    throw new Error('Quota exhausted: ' + data.message);
  }

  return data; // inspect data.has_violations and data.results
}

İlgili

• Kimlik Doğrulama ve API Anahtarları — anahtarlar, X-API-Key başlığı ve hız sınırları
• Hızlı Başlangıç Kılavuzu — birkaç dakika içinde ilk isteğiniz
• Metin Analizi — results nesnesinin ayrıntıları