# Lỗi

> Mọi lỗi là một mã có kiểu kèm mã HTTP và cờ thử lại — giống nhau trên HTTP, MCP, SDK và CLI.

Lỗi có một dạng duy nhất:

```json
{
  "error": { "code": "BUSY", "message": "profile already has a live session", "retryable": true, "details": { "session_id": "…" } },
  "correlation_id": "6f1c…"
}
```

Rẽ nhánh theo `code`, đừng theo `message`. `details` mang dữ kiện có kiểu khi có (phiên đang bận, trường bị sai, giới hạn đã chạm). Gửi kèm `correlation_id` khi liên hệ hỗ trợ hoặc gửi phản hồi.

## Các mã lỗi

| Mã | HTTP | Thử lại | Ý nghĩa |
|---|---|---|---|
| `UNAUTHENTICATED` | 401 | không | Thiếu, sai, đã thu hồi hoặc hết hạn khoá |
| `FORBIDDEN` | 403 | không | Khoá hoặc thành viên thiếu quyền |
| `REAUTH_REQUIRED` | 403 | không | Thao tác nhạy cảm cần đăng nhập lại trên web |
| `NOT_FOUND` | 404 | không | Không có gì bạn thấy được ở id đó |
| `VALIDATION_FAILED` | 422 | không | Dữ liệu vào sai schema; `details` liệt kê trường |
| `CONFLICT` | 409 | không | `expected_revision` cũ, hoặc dùng lại `command_id` với nội dung khác |
| `BUSY` | 409 | có | Tài nguyên đang dùng (ví dụ hồ sơ đang mở) |
| `STALE_GRANT` | 410 | không | Vé hoặc quyền đã bị thay thế |
| `QUOTA_EXCEEDED` | 429 | không | Đã chạm giới hạn của workspace |
| `RATE_LIMITED` | 429 | có | Quá nhiều yêu cầu; chờ theo `Retry-After` |
| `CAPACITY_UNAVAILABLE` | 503 | có | Hiện không còn sức chứa |
| `DEPENDENCY_UNAVAILABLE` | 503 | có | Dịch vụ Browlix phụ thuộc không trả lời |
| `UNSUPPORTED` | 501 | không | Không hỗ trợ ở đây (ví dụ phiên bản worker này) |
| `NETWORK_UNHEALTHY` | 424 | không | Kiểm tra proxy hoặc mạng thất bại |
| `INTEGRITY_FAILED` | 422 | không | Dữ liệu không qua kiểm tra toàn vẹn |
| `OUTCOME_UNKNOWN` | 202 | có | Đã nhận nhưng chưa xác nhận được kết quả; xem biên nhận |
| `RECOVERY_REQUIRED` | 409 | không | Phiên trước kết thúc không chắc chắn; [phục hồi](https://browlix.com/docs/sessions#phuc-hoi) trước |
| `SYNC_PENDING` | 409 | có | Máy khác giữ dữ liệu hồ sơ mới hơn |
| `FENCED` | 409 | không | Lượt giữ phiên của app đã cũ; [giữ lại phiên](https://browlix.com/docs/app-sessions#chan-ban-cu) |
| `UNKNOWN` | 500 | không | Ngoài dự kiến; báo kèm `correlation_id` |

## Thử lại

Chỉ thử lại các mã có cờ thử lại, có giãn cách, và — với lệnh — dùng **cùng** `command_id`. SDK tự làm việc này cho thao tác đọc và lệnh cùng id, tôn trọng `Retry-After` tối đa 10 giây.