Khái niệm
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:
{
"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 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 |
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.