رموز الأخطاء والاستجابات

يشير Discuse API إلى المشكلات بطريقتين: حالة خطأ HTTP مع message، أو استجابة عادية 200 توضّح حقولها ما حدث. تسرد هذه الصفحة كل حالة حتى تتمكّن من التعامل معها بشكل صحيح — وتشرح الحالة التي تُربك الكثيرين: نفاد حصة الفوترة ليس خطأ HTTP.

ما حالات HTTP التي يعيدها API؟

Status	When	What to do
200	نجاح — بما في ذلك حالة "نفاد الحصة"	افحص جسم الاستجابة؛ فالحالة 200 لا تعني دائمًا أن كل شيء على ما يرام (انظر أدناه)
400	فشل التحقق من صحة الطلب — محتوى فارغ، أو text يتجاوز 10,000 حرف، أو عدد كبير جدًا من عناوين URL للوسائط	أصلح الطلب؛ ولا تعِد المحاولة دون تغيير
401	مفتاح API مفقود أو غير صالح	تحقّق من ترويسة X-API-Key؛ ولا تعِد المحاولة دون تغيير
429	تجاوز حدّ المعدّل للمفتاح	انتظر ثم أعِد المحاولة بعد نافذة الدقيقة الواحدة
500	خطأ داخلي أو في خدمة تابعة	أعِد المحاولة مع زيادة تدريجية في مدة الانتظار

اقرأ message في أي استجابة غير 2xx. تعيد حالات فشل المصادقة 401، وتعيد حالات تجاوز حدّ المعدّل 429، وتعيد حالات فشل التحقق من صحة الطلب 400؛ وتعامل مع 5xx كأخطاء مؤقتة وأعِد المحاولة مع زيادة تدريجية في مدة الانتظار.

لماذا تكون حالة "نفاد الحصة" 200 وليست خطأ؟

عندما يستهلك مشروع ما الحصة الشهرية المسموح بها من طلبات API، يظل POST /api/v2/check يعيد 200 — مع التعامل مع المحتوى على أنه بلا مخالفات، ووجود message يوضح أن الحصة قد نفدت، وكائن usage يبيّن أن المتبقي صفر:

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

هذا مقصود: نفاد الحصة لا ينبغي أن يبدو كفشل في الخادم أو أن يوقف مسار المعالجة لديك باستثناء. تحقّق من usage.api_requests_remaining (وكذلك message) بدل الاعتماد على رمز الحالة. إذا كنت تسمح بالمرور عند 200، فقد يؤدي نفاد الحصة إلى تمرير المحتوى بصمت من دون فحص — لذلك تفرّع صراحةً بناءً على هذه الحقول.

كيف أقرأ استجابة ناجحة؟

أي 200 من /api/v2/check يتضمّن دائمًا has_violations وcached؛ أما الباقي فهو اختياري:

Field	Type	Meaning
has_violations	boolean	True إذا أشار أي فحص مفعّل إلى وجود مشكلة في المحتوى
cached	boolean	True إذا تم تقديم الاستجابة من ذاكرة تخزين مؤقتة لطلب مطابق حديث
message	string	يظهر عند نفاد الحصة (وفي إشعارات مشابهة لا تُعد أخطاء)
request_id	string	يُعاد كما هو إذا أرسلته
processing_time_ms	number	يظهر عندما يكون قياس الوقت مفعّلًا للمشروع
usage	object	api_requests_used, api_requests_limit, api_requests_remaining
results	object	تفاصيل كل فحص (spamfinder, sentiment, images, …) وعلامة hits على المستوى الأعلى

اعتمد على has_violations للحكم العام، ثم تعمّق في results.<check>.hit لمعرفة الفحص الذي تم تفعيله.

كيف يؤثر التخزين المؤقت في الاستجابات؟

تُزال الطلبات المتطابقة للمشروع نفسه من التكرار: يعيد الطلب المكرر cached: true مع النتيجة نفسها. التخزين المؤقت يكون لكل مشروع على حدة. لاحظ أن الطلب المخزّن مؤقتًا لا يزال يُحتسب ضمن حصة طلبات API لديك — فهو يوفّر وقت المعالجة، لا الحصة.

يمكنك إرفاق request_id بالطلب لأغراض الربط والتتبع لديك؛ وستتم إعادته كما هو في الاستجابة.

عميل بسيط وصحيح

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
}

مواضيع ذات صلة

• المصادقة ومفاتيح API — المفاتيح، وترويسة X-API-Key، وحدود المعدّل
• دليل البدء السريع — طلبك الأول خلال بضع دقائق
• تحليل النصوص — كائن results بالتفصيل