त्रुटियाँ और स्टेटस कोड

finlight API किसी अनुरोध के परिणाम को दर्शाने के लिए पारंपरिक HTTP स्टेटस कोड का उपयोग करता है। 2xx स्टेटस का अर्थ सफलता है; 4xx का अर्थ है कि अनुरोध अस्वीकार कर दिया गया (आमतौर पर कुछ जिसे आप ठीक कर सकते हैं); 5xx का अर्थ है हमारी ओर से कोई समस्या। प्रत्येक त्रुटि एक JSON निकाय लौटाती है जो बताती है कि क्या गलत हुआ।

ध्यान दें: REST और WebSocket अनुरोध X-API-KEY हेडर से प्रमाणित होते हैं। गायब या अमान्य कुंजी 401 लौटाती है। (Webhook डिलीवरी प्रमाणीकरण — वे हेडर जो finlight आपके एंडपॉइंट पर भेजता है — अलग है; Webhook प्रमाणीकरण देखें।)

स्टेटस कोड एक नज़र में

400 — Bad Request

तब लौटाया जाता है जब क्वेरी पैरामीटर या अनुरोध निकाय सत्यापन में विफल हो जाते हैं, या जब query स्ट्रिंग अमान्य फ़ील्ड-स्तरीय सिंटैक्स का उपयोग करती है।

अमान्य पैरामीटर:

{
  "statusCode": 400,
  "message": ["pageSize must not be greater than 100"],
  "error": "Bad Request"
}

अमान्य query सिंटैक्स (POST /v2/articles):

{
  "statusCode": 400,
  "message": [
    {
      "property": "query",
      "constraints": { "query": "Invalid query syntax near 'ticker:'" }
    }
  ],
  "error": "Bad Request"
}

सही query सिंटैक्स के लिए उन्नत क्वेरी निर्माण देखें।

401 — Unauthorized

X-API-KEY हेडर गायब है, त्रुटिपूर्ण है, या मान्य कुंजी नहीं है।

{
  "statusCode": 401,
  "message": "Unauthorized"
}

finlight डैशबोर्ड में अपनी कुंजी प्राप्त करें या बदलें।

403 — Forbidden

अनुरोध प्रमाणित है, लेकिन आपके प्लान में अनुरोधित क्षमता शामिल नहीं है — उदाहरण के लिए, ऐसे प्लान पर पूर्ण लेख सामग्री का अनुरोध करना जो इसे शामिल नहीं करता।

{
  "statusCode": 403,
  "message": "Your subscription does not allow calling the extended article content"
}

प्रत्येक प्लान में कौन-सी क्षमताएँ शामिल हैं, यह जानने के लिए दर सीमाएँ और कोटा देखें।

404 — Not Found

अनुरोधित संसाधन मौजूद नहीं है — सबसे आम रूप से ऐसे link के साथ GET /v2/articles/by-link जिसे finlight ने इंडेक्स नहीं किया है।

{
  "statusCode": 404,
  "message": "Article not found"
}

422 — Unprocessable Entity

कुछ एंडपॉइंट वैश्विक सत्यापनकर्ता के माध्यम से सत्यापन करते हैं, जो फ़ील्ड-कुंजीबद्ध त्रुटि मानचित्र लौटाता है। प्रत्येक कुंजी वह फ़ील्ड है जिसमें त्रुटि है; मान विफल हुई बाधाओं को सूचीबद्ध करता है।

{
  "status": 422,
  "errors": {
    "language": "language must be a string"
  }
}

ध्यान दें: मार्ग के आधार पर, सत्यापन विफलताएँ 400 (लेख एंडपॉइंट पर) या 422 (वैश्विक सत्यापनकर्ता) के रूप में दिख सकती हैं — दोनों एक त्रुटिपूर्ण अनुरोध को दर्शाते हैं। यह देखने के लिए निकाय का निरीक्षण करें कि कौन-सा फ़ील्ड विफल हुआ।

429 — Too Many Requests

आपने किसी उपयोग सीमा को पार कर लिया है। दो अलग-अलग मामले हैं, प्रत्येक का एक विशिष्ट संदेश है:

मासिक अनुरोध कोटा पार:

{
  "statusCode": 429,
  "message": "Throttling Exception: Exceeded token limit of 5000 for the current period."
}

बर्स्ट (अल्पकालिक) दर पार:

{
  "statusCode": 429,
  "message": "Throttling Exception: Exceeded rate limit of 10 requests per 10 seconds."
}

ध्यान दें: finlight वर्तमान में Retry-After या दर-सीमा हेडर नहीं लौटाता। बर्स्ट 429 के लिए, पीछे हटें और लगभग 10 सेकंड बाद पुनः प्रयास करें। मासिक कोटा 429 के लिए, आपके अगले बिलिंग अवधि की शुरुआत में (या अपग्रेड के बाद) अनुरोध फिर से सफल होंगे। दर सीमाएँ और कोटा देखें।

500 — Internal Server Error

finlight की ओर से एक अप्रत्याशित त्रुटि हुई। ये अस्थायी होती हैं — बैकऑफ़ के साथ पुनः प्रयास करें, और यदि यह बनी रहती है, तो सहायता के माध्यम से संपर्क करें।

{
  "statusCode": 500,
  "message": "Internal server error"
}

त्रुटियों को अच्छी तरह संभालना

• हमेशा पहले स्टेटस कोड जाँचें, फिर विवरण के लिए JSON निकाय पढ़ें।
• 4xx (429 को छोड़कर) आपकी गलती है — अनुरोध ठीक करें; बिना बदलाव के पुनः प्रयास करने से मदद नहीं मिलेगी।
• 429 और 5xx पुनः प्रयास योग्य हैं — एक्सपोनेंशियल बैकऑफ़ का उपयोग करें। बर्स्ट 429 के लिए, लगभग 10 सेकंड पर्याप्त हैं।
• WebSocket त्रुटियाँ HTTP स्टेटस के बजाय सॉकेट पर error सर्वर संदेश के रूप में आती हैं — WebSocket मूल बातें देखें।
• Webhook डिलीवरी विफलताएँ (आपके एंडपॉइंट पर) डैशबोर्ड में ट्रैक की जाती हैं, आपको समकालिक रूप से नहीं लौटाई जातीं — Webhook परीक्षण देखें।