# Errors & Error Handling

Synapse ใช้ HTTP status code มาตรฐานพร้อมรูปแบบ error response ที่สม่ำเสมอ เอกสารหน้านี้อธิบายวิธีตีความและกู้คืนจาก error

## รูปแบบ Error Response

error ทั้งหมดส่งกลับเป็น JSON ด้วยโครงสร้างนี้:

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

| Field | คำอธิบาย |
|-------|-------------|
| `statusCode` | HTTP status code |
| `error` | ชื่อ HTTP status |
| `message` | คำอธิบาย error ที่มนุษย์อ่านได้ |
| `docs` | URL ไปยังเอกสารที่เกี่ยวข้อง (เมื่อเกี่ยวข้อง) |

## HTTP Status Codes

### 200 OK

สำเร็จ request ถูกประมวลผลถูกต้อง

### 201 Created

สำเร็จ สร้าง resource ใหม่ (เช่น `POST /memory`)

### 204 No Content

สำเร็จ ไม่มี body ส่งกลับ (เช่น `DELETE /memory/:id`)

### 400 Bad Request

request ผิดรูปแบบ สาเหตุทั่วไป:

- ขาด JSON field ที่จำเป็น
- ไวยากรณ์ JSON ไม่ถูกต้อง
- ค่า enum ไม่ถูกต้อง (เช่น category ผิด)

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

**วิธีแก้:** ตรวจสอบ request body กับ API docs ตรวจสอบว่า field ที่จำเป็นทั้งหมดมีและมีค่าที่ถูกต้อง

### 401 Unauthorized

การยืนยันตัวตนล้มเหลว สาเหตุทั่วไป:

- ขาด `Authorization` header
- 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"
}
```

**วิธีแก้:** ตรวจสอบ token ของคุณ ดู [Authentication](/docs/getting-started/authentication)

### 403 Forbidden

คุณยืนยันตัวตนแล้วแต่ไม่ได้รับอนุญาตให้ทำ action นี้ สาเหตุทั่วไป:

- พยายามลบ mind ของผู้ใช้อื่น
- พยายาม verify memory ด้วย Mind Key (ต้องใช้ JWT)
- Mind ถูกปิดใช้งาน

**วิธีแก้:** ตรวจสอบว่าคุณใช้ประเภท token ที่ถูกต้องสำหรับ endpoint นี้

### 404 Not Found

path หรือ resource ที่ร้องขอไม่มีอยู่

> [!CRITICAL]
> **อย่าเดา path ของ endpoint** มีเพียง path ที่แสดงใน `GET /endpoints` เท่านั้นที่มีอยู่ หากคุณได้ 404 แสดงว่าคุณใช้ path ผิด

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

**วิธีแก้:** เรียก `GET /endpoints` เพื่อดูรายการ endpoint ที่ถูกต้อง เปรียบเทียบ URL ของคุณกับรายการทีละตัวอักษร

### 409 Conflict

request ขัดแย้งกับสถานะที่มีอยู่ สาเหตุทั่วไป:

- พยายามลงทะเบียนด้วย email ที่มีอยู่แล้ว
- ซ้ำ webhook URL

**วิธีแก้:** ใช้ค่าอื่น หรือใช้ `PUT` เพื่ออัปเดต resource ที่มีอยู่

### 429 Too Many Requests

คุณกระทบ rate limit ใช้เฉพาะกับ auth ผ่าน `?key=` query parameter (60/นาที)

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

Response headers:

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

**วิธีแก้:** เปลี่ยนไปใช้ `Authorization: Bearer` header (ไม่จำกัดอัตรา) หรือรอ `Retry-After` วินาที

### 500 Internal Server Error

server error ไม่ควรเกิดขึ้น — หากเกิด ถือเป็น bug

**วิธีแก้:**

1. Retry ด้วย exponential backoff (1s, 2s, 4s, 8s)
2. ตรวจสอบ `GET /health` เพื่อดูว่า server ยังทำงานอยู่หรือไม่
3. หากยังเกิดขึ้นเรื่อย ๆ ให้รายงาน error

### 503 Service Unavailable

server ล่มชั่วคราว (เช่น ระหว่าง deploy, database migration)

**วิธีแก้:** รอแล้ว retry ตรวจสอบ `GET /health`

## รูปแบบการกู้คืน

### Retry ด้วย exponential backoff

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

### การจัดการ auth error

```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
```

## สถานการณ์ error ทั่วไป

### "Mind Key fehlt oder ungültig"

- คุณลืม `Authorization` header
- คุณใช้ `?key=` แต่ key ผิด
- คุณใช้ JWT ในที่ที่ต้องใช้ Mind Key

### "Route not found"

- คุณเดา path ที่ไม่มีอยู่
- คุณใช้ verb ผิด (เช่น `GET /memory` เทียบกับ `POST /memory`)
- ตรวจสอบ `GET /endpoints` สำหรับ path ที่ถูกต้อง

### "Rate limit exceeded"

- คุณใช้ `?key=` และเกิน 60 req/min
- เปลี่ยนไปใช้ `Authorization: Bearer` header

## ขั้นตอนถัดไป

- [Authentication](/docs/getting-started/authentication)
- [API Overview](/docs/api/overview)
- [Rate Limits](/docs/api/rate-limits)