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:

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

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)

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

{
  "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.

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.

{
  "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).

{
  "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

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

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
• Tổng quan API
• Giới hạn tốc độ