# Lỗi & Xử lý lỗi
SUMMARY: Mã trạng thái HTTP, định dạng phản hồi lỗi, và cách khôi phục từ các lỗi phổ biến.

KEY CONTEXT:
Error format: { statusCode, error, message, docs? }
Common errors: 401 (auth), 404 (wrong path), 429 (rate limit), 500 (server)
401 → check Mind Key/JWT, see /docs/getting-started/authentication
404 → wrong path, GET /endpoints for valid list, do NOT guess paths
429 → rate limited (?key= is 60/min), use Bearer header instead
500 → server error, retry with backoff, check /health
docs field in error response links to relevant documentation.

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:
[CODE BLOCK]
| Trường | Mô tả |
|-------|-------------|
|  | Mã trạng thái HTTP |
|  | Tên trạng thái HTTP |
|  | Mô tả lỗi dành cho người đọc |
|  | 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ụ ).
204 No Content
Thành công. Không có body trả về (ví dụ ).
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)
[CODE BLOCK]
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 
- 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)
[CODE BLOCK]
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.
> [!CRITICAL]
> KHÔNG đoán đường dẫn endpoint. Chỉ những đường dẫn liệt kê trong
>  mới tồn tại. Nếu bạn nhận 404, bạn đã dùng sai đường dẫn.
[CODE BLOCK]
Khắc phục: Gọi  để 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  để 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ố  (60/phút).
[CODE BLOCK]
Header phản hồi:
[CODE BLOCK]
Khắc phục: Chuyển sang header  (không giới hạn tốc
độ), hoặc đợi  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  để 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 .
Mẫu khôi phục
Thử lại với exponential backoff
[CODE BLOCK]
Xử lý lỗi xác thực
[CODE BLOCK]
Kịch bản lỗi phổ biến
"Mind Key fehlt oder ungültig"
- Bạn quên header 
- Bạn dùng  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ụ  thay vì )
- Kiểm tra  để xem đường dẫn hợp lệ
"Rate limit exceeded"
- Bạn đang dùng  và vượt quá 60 yêu cầu/phút
- Chuyển sang header 
Bước tiếp theo
- Xác thực
- Tổng quan API
- Giới hạn tốc độ