Kode Error dan Respons

Discuse API memberi sinyal adanya masalah dengan dua cara: status error HTTP disertai message, atau respons normal 200 yang field-nya menjelaskan apa yang terjadi. Halaman ini mencantumkan setiap kasus agar Anda dapat menanganinya dengan benar — sekaligus menjelaskan satu hal yang sering membingungkan: habisnya kuota penagihan bukan error HTTP.

Status HTTP apa saja yang dikembalikan API?

Status	Kapan	Yang harus dilakukan
200	Berhasil — termasuk kasus "kuota habis"	Periksa isi respons; 200 tidak selalu berarti semuanya aman (lihat di bawah)
400	Validasi permintaan gagal — konten kosong, text lebih dari 10.000 karakter, atau URL media terlalu banyak	Perbaiki permintaan; jangan mencoba ulang tanpa perubahan
401	API key tidak ada atau tidak valid	Periksa header X-API-Key; jangan mencoba ulang tanpa perubahan
429	Batas laju untuk key terlampaui	Tunggu lalu coba lagi setelah jendela satu menit
500	Error downstream/internal	Coba lagi dengan backoff

Baca message pada respons non-2xx apa pun. Kegagalan autentikasi mengembalikan 401, kegagalan batas laju mengembalikan 429, dan kegagalan validasi permintaan mengembalikan 400; perlakukan 5xx sebagai sementara dan coba lagi dengan backoff.

Mengapa "kuota habis" berupa 200, bukan error?

Saat sebuah proyek menghabiskan jatah permintaan API bulanannya, POST /api/v2/check tetap mengembalikan 200 — dengan konten diperlakukan seolah tidak memiliki pelanggaran, sebuah message yang menjelaskan bahwa kuota telah habis, dan objek usage yang menunjukkan sisa nol:

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

Ini disengaja: habisnya kuota tidak seharusnya terlihat seperti kegagalan server atau memblokir pipeline Anda dengan exception. Periksa usage.api_requests_remaining (dan message), bukan hanya mengandalkan kode status. Jika Anda membiarkan lolos pada 200, kuota yang habis akan diam-diam membuat konten lewat tanpa diperiksa — jadi buat percabangan secara eksplisit berdasarkan field-field ini.

Bagaimana cara membaca respons yang berhasil?

Respons 200 dari /api/v2/check selalu membawa has_violations dan cached; sisanya opsional:

Field	Tipe	Arti
has_violations	boolean	True jika pemeriksaan yang diaktifkan menandai konten
cached	boolean	True jika disajikan dari cache permintaan identik terbaru
message	string	Ada saat kuota habis (dan pemberitahuan non-error serupa)
request_id	string	Dikembalikan jika Anda mengirimkannya
processing_time_ms	number	Ada saat pengukuran waktu diaktifkan untuk proyek
usage	object	api_requests_used, api_requests_limit, api_requests_remaining
results	object	Detail per pemeriksaan (spamfinder, sentiment, images, …) dan flag tingkat atas hits

Gunakan has_violations untuk keputusan keseluruhan, lalu telusuri results.<check>.hit untuk mengetahui pemeriksaan mana yang terpicu.

Bagaimana caching memengaruhi respons?

Permintaan identik untuk proyek yang sama akan di-deduplikasi: pengulangan mengembalikan cached: true dengan hasil yang sama. Caching berlaku per proyek. Perlu diperhatikan bahwa permintaan yang di-cache tetap dihitung terhadap kuota permintaan API Anda — caching menghemat waktu pemrosesan, bukan kuota.

Anda dapat menyertakan request_id pada permintaan untuk korelasi internal Anda; nilai tersebut akan dikembalikan dalam respons.

Klien minimal yang benar

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
}

Terkait

• Autentikasi dan API Key — key, header X-API-Key, dan batas laju
• Panduan Mulai Cepat — permintaan pertama Anda dalam beberapa menit
• Analisis Teks — objek results secara mendetail