त्रुटि और प्रतिक्रिया कोड

Discuse API समस्याओं का संकेत दो तरीकों से देता है: message के साथ HTTP त्रुटि स्थिति, या सामान्य 200 प्रतिक्रिया जिसके फ़ील्ड बताते हैं कि क्या हुआ। यह पेज हर स्थिति सूचीबद्ध करता है ताकि आप उन्हें सही ढंग से संभाल सकें — और उस एक मामले को समझाता है जो लोगों को उलझा देता है: बिलिंग-कोटा खत्म होना HTTP त्रुटि नहीं है।

API कौन-से HTTP स्टेटस लौटाता है?

Status	कब	क्या करें
200	सफलता — इसमें "quota exhausted" वाला मामला भी शामिल है	प्रतिक्रिया बॉडी देखें; 200 हमेशा हरी झंडी नहीं होता (नीचे देखें)
400	अनुरोध सत्यापन विफल — खाली सामग्री, 10,000 वर्णों से अधिक text, या बहुत अधिक मीडिया URL	अनुरोध ठीक करें; बिना बदलाव दोबारा कोशिश न करें
401	API key गायब या अमान्य	X-API-Key हेडर जाँचें; बिना बदलाव दोबारा कोशिश न करें
429	key के लिए rate limit पार हो गई	थोड़ा रुकें और एक मिनट की विंडो के बाद दोबारा कोशिश करें
500	कोई downstream/internal त्रुटि	backoff के साथ दोबारा कोशिश करें

किसी भी non-2xx प्रतिक्रिया में message पढ़ें। प्रमाणीकरण विफलताएँ 401 लौटाती हैं, rate-limit विफलताएँ 429 लौटाती हैं, और request-validation विफलताएँ 400 लौटाती हैं; 5xx को अस्थायी मानें और backoff के साथ दोबारा कोशिश करें।

"quota exhausted" 200 क्यों है, त्रुटि क्यों नहीं?

जब कोई प्रोजेक्ट अपनी मासिक API-request सीमा पूरी कर लेता है, तब भी POST /api/v2/check 200 लौटाता है — सामग्री को ऐसा माना जाता है जैसे उसमें कोई उल्लंघन नहीं है, message बताता है कि quota खत्म हो चुका है, और 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
  }
}

यह जानबूझकर किया गया है: quota खत्म होना server failure जैसा नहीं दिखना चाहिए और न ही आपके pipeline को exception से रोकना चाहिए। status code पर निर्भर रहने के बजाय usage.api_requests_remaining (और message) जाँचें। अगर आप 200 पर fail open करते हैं, तो quota खत्म होने पर सामग्री बिना जाँचे चुपचाप आगे निकल जाएगी — इसलिए इन फ़ील्ड के आधार पर स्पष्ट रूप से branch करें।

सफल प्रतिक्रिया को कैसे पढ़ना चाहिए?

/api/v2/check से आने वाली 200 प्रतिक्रिया में हमेशा has_violations और cached होते हैं; बाकी वैकल्पिक है:

Field	Type	अर्थ
has_violations	boolean	True अगर किसी भी सक्षम check ने सामग्री को flag किया है
cached	boolean	True अगर हाल के समान अनुरोध के cache से serve किया गया है
message	string	quota exhaustion (और इसी तरह की non-error notices) पर मौजूद
request_id	string	अगर आपने भेजा था, तो वही वापस लौटाया जाता है
processing_time_ms	number	जब प्रोजेक्ट के लिए timing सक्षम हो, तब मौजूद
usage	object	api_requests_used, api_requests_limit, api_requests_remaining
results	object	हर check का विवरण (spamfinder, sentiment, images, …) और top-level hits flag

कुल verdict के लिए has_violations के आधार पर निर्णय लें, फिर कौन-सा check fired हुआ यह देखने के लिए results.<check>.hit में जाएँ।

caching प्रतिक्रियाओं को कैसे प्रभावित करती है?

उसी प्रोजेक्ट के लिए समान अनुरोध de-duplicate किए जाते हैं: दोहराए गए अनुरोध में उसी परिणाम के साथ cached: true लौटता है। Caching प्रति प्रोजेक्ट होती है। ध्यान दें कि cached request फिर भी आपके API-request quota में गिना जाता है — यह processing time बचाता है, quota नहीं।

आप अपने correlation के लिए अनुरोध में request_id जोड़ सकते हैं; यह प्रतिक्रिया में वापस लौटा दिया जाता है।

एक न्यूनतम, सही client

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
}

संबंधित

• Authentication और API Keys — keys, X-API-Key हेडर, और rate limits
• Quick Start Guide — कुछ ही मिनटों में आपका पहला अनुरोध
• Text Analysis — results ऑब्जेक्ट विस्तार से