त्रुटियाँ और त्रुटि प्रबंधन

Synapse एक सुसंगत त्रुटि प्रतिक्रिया प्रारूप के साथ मानक HTTP स्टेटस कोड का उपयोग करता है। यह पृष्ठ बताता है कि त्रुटियों की व्याख्या कैसे करें और उनसे कैसे उबरें।

त्रुटि प्रतिक्रिया प्रारूप

सभी त्रुटियाँ इस संरचना के साथ JSON लौटाती हैं:

{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Mind Key fehlt oder ungültig.",
  "docs": "https://synapse.schaefer.zone/docs/getting-started/authentication"
}

HTTP स्टेटस कोड

200 OK

सफलता। अनुरोध सही ढंग से संसाधित किया गया।

201 Created

सफलता। एक नया संसाधन बनाया गया (जैसे POST /memory)।

204 No Content

सफलता। कोई बॉडी वापस नहीं लौटाई गई (जैसे DELETE /memory/:id)।

400 Bad Request

अनुरोध विकृत था। सामान्य कारण:

• आवश्यक JSON फ़ील्ड्स गायब
• अमान्य JSON सिंटैक्स
• अमान्य enum मान (जैसे गलत श्रेणी)

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "category must be one of: identity, preference, fact, project, skill, mistake, context, note, credentials"
}

समाधान: API दस्तावेज़ों के विरुद्ध अनुरोध बॉडी की जाँच करें। सुनिश्चित करें कि सभी आवश्यक फ़ील्ड्स मौजूद हैं और वैध मान रखते हैं।

401 Unauthorized

प्रमाणीकरण विफल। सामान्य कारण:

• Authorization हेडर गायब
• अमान्य Mind Key या JWT
• Mind Key का उपयोग जहाँ JWT आवश्यक है (या इसके विपरीत)

{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Mind Key fehlt oder ungültig.",
  "docs": "https://synapse.schaefer.zone/docs/getting-started/authentication"
}

समाधान: अपने टोकन को सत्यापित करें। प्रमाणीकरण देखें।

403 Forbidden

आप प्रमाणित हैं लेकिन यह क्रिया करने की अनुमति नहीं है। सामान्य कारण:

• किसी अन्य उपयोगकर्ता के mind को हटाने का प्रयास
• Mind Key से मेमोरी सत्यापित करने का प्रयास (JWT आवश्यक)
• Mind अक्षम है

समाधान: जाँचें कि आप इस एंडपॉइंट के लिए सही टोकन प्रकार का उपयोग कर रहे हैं।

404 Not Found

अनुरोधित पाथ या संसाधन मौजूद नहीं है।

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Route GET /memory/list not found",
  "docs": "https://synapse.schaefer.zone/docs/api/errors"
}

समाधान: वैध एंडपॉइंट्स की सूची देखने के लिए GET /endpoints कॉल करें। अपने URL की सूची के साथ वर्ण-दर-वर्ण तुलना करें।

409 Conflict

अनुरोध मौजूदा स्थिति से टकराता है। सामान्य कारण:

• पहले से मौजूद ईमेल के साथ पंजीकरण का प्रयास
• डुप्लिकेट webhook URL

समाधान: एक अलग मान का उपयोग करें, या मौजूदा संसाधन को अपडेट करने के लिए PUT का उपयोग करें।

429 Too Many Requests

आपने रेट लिमिट हिट कर ली। केवल ?key= क्वेरी पैरामीटर प्रमाणीकरण (60/min) पर लागू होता है।

{
  "statusCode": 429,
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Use Authorization header for unlimited access."
}

प्रतिक्रिया हेडर:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
Retry-After: 42

समाधान: Authorization: Bearer हेडर पर स्विच करें (कोई रेट लिमिट नहीं), या Retry-After सेकंड प्रतीक्षा करें।

500 Internal Server Error

सर्वर त्रुटि। ऐसा नहीं होना चाहिए — यदि होता है, तो यह एक बग है।

समाधान:

1. घातीय बैकऑफ़ के साथ पुनः प्रयास करें (1s, 2s, 4s, 8s)
2. जाँचें कि सर्वर चालू है या नहीं GET /health
3. यदि लगातार हो, तो त्रुटि की रिपोर्ट करें

503 Service Unavailable

सर्वर अस्थायी रूप से बंद है (जैसे परिनियोजन, डेटाबेस माइग्रेशन के दौरान)।

समाधान: प्रतीक्षा करें और पुनः प्रयास करें। GET /health जाँचें।

पुनर्प्राप्ति पैटर्न

घातीय बैकऑफ़ के साथ पुनः प्रयास

import time
import requests

def call_with_retry(url, max_retries=3):
    for attempt in range(max_retries):
        try:
            r = requests.get(url, headers={"Authorization": f"Bearer {KEY}"})
            if r.status_code == 429:
                wait = int(r.headers.get("Retry-After", 60))
                time.sleep(wait)
                continue
            if r.status_code >= 500:
                time.sleep(2 ** attempt)
                continue
            return r
        except requests.RequestException:
            time.sleep(2 ** attempt)
    raise Exception(f"Failed after {max_retries} retries")

प्रमाणीकरण त्रुटि प्रबंधन

def safe_call(url, key):
    r = requests.get(url, headers={"Authorization": f"Bearer {key}"})
    if r.status_code == 401:
        # Mind Key invalid — alert user
        raise AuthError("Mind Key invalid or expired")
    return r

सामान्य त्रुटि परिदृश्य

"Mind Key fehlt oder ungültig"

• आप Authorization हेडर भूल गए
• आपने ?key= उपयोग किया लेकिन कुंजी गलत है
• आप Mind Key आवश्यक होने पर JWT उपयोग कर रहे हैं

"Route not found"

• आपने ऐसा पाथ अनुमानित किया जो मौजूद नहीं है
• आपने क्रिया गलत उपयोग की (जैसे GET /memory vs POST /memory)
• वैध पाथ के लिए GET /endpoints जाँचें

"Rate limit exceeded"

• आप ?key= उपयोग कर रहे हैं और 60 req/min पार कर गए
• Authorization: Bearer हेडर पर स्विच करें

अगले कदम

• प्रमाणीकरण
• API Overview
• Rate Limits