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

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

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

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

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

| फ़ील्ड | विवरण |
|-------|-------------|
| `statusCode` | HTTP स्टेटस कोड |
| `error` | HTTP स्टेटस नाम |
| `message` | मानव-पठनीय त्रुटि विवरण |
| `docs` | प्रासंगिक दस्तावेज़ीकरण का URL (जब लागू हो) |

## HTTP स्टेटस कोड

### 200 OK

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

### 201 Created

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

### 204 No Content

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

### 400 Bad Request

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

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

```json
{
  "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 आवश्यक है (या इसके विपरीत)

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

**समाधान:** अपने टोकन को सत्यापित करें। [प्रमाणीकरण](/docs/getting-started/authentication) देखें।

### 403 Forbidden

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

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

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

### 404 Not Found

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

> [!CRITICAL]
> **एंडपॉइंट पाथ का अनुमान न लगाएँ।** केवल `GET /endpoints` में सूचीबद्ध पाथ मौजूद हैं। यदि आपको 404 मिलता है, तो आपने गलत पाथ का उपयोग किया है।

```json
{
  "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) पर लागू होता है।

```json
{
  "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` जाँचें।

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

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

```python
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")
```

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

```python
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` हेडर पर स्विच करें

## अगले कदम

- [प्रमाणीकरण](/docs/getting-started/authentication)
- [API Overview](/docs/api/overview)
- [Rate Limits](/docs/api/rate-limits)