# Lỗi & Xử lý lỗi

Synapse sử dụng các mã trạng thái HTTP chuẩn với định dạng phản hồi lỗi nhất
quán. Trang này giải thích cách diễn giải và khôi phục từ lỗi.

## Định dạng phản hồi lỗi

Tất cả lỗi trả về JSON với cấu trúc sau:

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

| Trường | Mô tả |
|-------|-------------|
| `statusCode` | Mã trạng thái HTTP |
| `error` | Tên trạng thái HTTP |
| `message` | Mô tả lỗi dành cho người đọc |
| `docs` | URL tới tài liệu liên quan (khi áp dụng) |

## Mã trạng thái HTTP

### 200 OK

Thành công. Yêu cầu được xử lý đúng.

### 201 Created

Thành công. Một tài nguyên mới được tạo (ví dụ `POST /memory`).

### 204 No Content

Thành công. Không có body trả về (ví dụ `DELETE /memory/:id`).

### 400 Bad Request

Yêu cầu sai định dạng. Nguyên nhân phổ biến:

- Thiếu trường JSON bắt buộc
- Cú pháp JSON không hợp lệ
- Giá trị enum không hợp lệ (ví dụ sai danh mục)

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

**Khắc phục:** Kiểm tra body yêu cầu so với tài liệu API. Đảm bảo tất cả
trường bắt buộc đều có và có giá trị hợp lệ.

### 401 Unauthorized

Xác thực thất bại. Nguyên nhân phổ biến:

- Thiếu header `Authorization`
- Mind Key hoặc JWT không hợp lệ
- Sử dụng Mind Key nơi yêu cầu JWT (hoặc ngược lại)

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

**Khắc phục:** Xác minh token của bạn. Xem [Xác thực](/docs/getting-started/authentication).

### 403 Forbidden

Bạn đã được xác thực nhưng không được phép thực hiện hành động này. Nguyên nhân phổ biến:

- Cố xóa mind của người dùng khác
- Cố xác minh bộ nhớ bằng Mind Key (yêu cầu JWT)
- Mind bị vô hiệu hóa

**Khắc phục:** Kiểm tra xem bạn có đang sử dụng đúng loại token cho endpoint này không.

### 404 Not Found

Đường dẫn hoặc tài nguyên yêu cầu không tồn tại.

> [!CRITICAL]
> **KHÔNG đoán đường dẫn endpoint.** Chỉ những đường dẫn liệt kê trong
> `GET /endpoints` mới tồn tại. Nếu bạn nhận 404, bạn đã dùng sai đường dẫn.

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

**Khắc phục:** Gọi `GET /endpoints` để xem danh sách endpoint hợp lệ. So sánh
URL của bạn với danh sách từng ký tự.

### 409 Conflict

Yêu cầu xung đột với trạng thái hiện tại. Nguyên nhân phổ biến:

- Cố đăng ký với email đã tồn tại
- Trùng URL webhook

**Khắc phục:** Sử dụng giá trị khác, hoặc dùng `PUT` để cập nhật tài nguyên hiện có.

### 429 Too Many Requests

Bạn đã đạt giới hạn tốc độ. Chỉ áp dụng cho xác thực qua tham số `?key=` (60/phút).

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

Header phản hồi:

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

**Khắc phục:** Chuyển sang header `Authorization: Bearer` (không giới hạn tốc
độ), hoặc đợi `Retry-After` giây.

### 500 Internal Server Error

Lỗi server. Điều này không nên xảy ra — nếu xảy ra, đó là bug.

**Khắc phục:**

1. Thử lại với exponential backoff (1s, 2s, 4s, 8s)
2. Kiểm tra `GET /health` để xem server có hoạt động không
3. Nếu liên tục, báo cáo lỗi

### 503 Service Unavailable

Server tạm thời ngừng (ví dụ trong quá trình triển khai, di chuyển database).

**Khắc phục:** Đợi và thử lại. Kiểm tra `GET /health`.

## Mẫu khôi phục

### Thử lại với 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")
```

### Xử lý lỗi xác thực

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

## Kịch bản lỗi phổ biến

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

- Bạn quên header `Authorization`
- Bạn dùng `?key=` nhưng key sai
- Bạn đang dùng JWT nơi yêu cầu Mind Key

### "Route not found"

- Bạn đã đoán một đường dẫn không tồn tại
- Bạn dùng sai verb (ví dụ `GET /memory` thay vì `POST /memory`)
- Kiểm tra `GET /endpoints` để xem đường dẫn hợp lệ

### "Rate limit exceeded"

- Bạn đang dùng `?key=` và vượt quá 60 yêu cầu/phút
- Chuyển sang header `Authorization: Bearer`

## Bước tiếp theo

- [Xác thực](/docs/getting-started/authentication)
- [Tổng quan API](/docs/api/overview)
- [Giới hạn tốc độ](/docs/api/rate-limits)