خطاها و کدهای پاسخ

API Discuse مشکلات را به دو روش اعلام می‌کند: یا با یک وضعیت خطای HTTP همراه با یک message، یا با یک پاسخ عادی 200 که فیلدهای آن نشان می‌دهند چه اتفاقی افتاده است. این صفحه همهٔ حالت‌ها را فهرست می‌کند تا بتوانید آن‌ها را درست مدیریت کنید — و موردی را توضیح می‌دهد که خیلی‌ها را به اشتباه می‌اندازد: تمام‌شدن سهمیهٔ صورتحساب خطای HTTP نیست.

API چه وضعیت‌های HTTP برمی‌گرداند؟

Status	When	What to do
200	موفقیت — از جمله حالت «تمام‌شدن سهمیه»	بدنهٔ پاسخ را بررسی کنید؛ 200 همیشه به معنی مجوز عبور نیست (پایین‌تر را ببینید)
400	اعتبارسنجی درخواست ناموفق بوده — محتوای خالی، text با بیش از ۱۰٬۰۰۰ نویسه، یا تعداد بیش از حد URL رسانه	درخواست را اصلاح کنید؛ بدون تغییر دوباره تلاش نکنید
401	کلید API وجود ندارد یا نامعتبر است	هدر X-API-Key را بررسی کنید؛ بدون تغییر دوباره تلاش نکنید
429	محدودیت نرخ برای این کلید رد شده است	کمی صبر کنید و پس از پنجرهٔ یک‌دقیقه‌ای دوباره تلاش کنید
500	خطای داخلی یا خطا در سرویس پایین‌دستی	با وقفهٔ افزایشی دوباره تلاش کنید

در هر پاسخ غیر 2xx مقدار message را بخوانید. خطاهای احراز هویت 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
  }
}

این رفتار عمدی است: تمام‌شدن سهمیه نباید شبیه خرابی سرور به نظر برسد یا با یک exception مسیر پردازش شما را متوقف کند. به‌جای تکیه بر کد وضعیت، 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 با جزئیات کامل