Lỗi

Các lỗi dùng chung một phong bì (xem tổng quan). Rẽ nhánh theo code, ghi log meta.request_id, và coi message là văn bản tiếng Anh dành cho con người.

Lỗi phía client

Mã	Trạng thái	Ý nghĩa và cách xử lý
validation_failed	400	Một trường không vượt qua kiểm tra hợp lệ. field cho biết tên trường; details giải thích. Hãy sửa trường đó.
bad_request	400	Hoàn toàn không đọc được yêu cầu: JSON sai định dạng, luồng Content-Encoding bị hỏng, body bị ngắt giữa chừng. Không có trường nào cần sửa; hãy kiểm tra đường truyền.
validation_error	400	X-Account-Id được gửi đến endpoint cấm header này (/auth/login, /auth/refresh, /auth/swap-company, /auth/logout).
cursor_expired	400	Con trỏ phân trang đã quá 24 giờ. Hãy bắt đầu liệt kê lại.
unauthenticated	401	Thiếu token hoặc token không hợp lệ. Làm mới phiên hoặc kiểm tra khóa.
invalid_signature	401	Chữ ký webhook không xác minh được. Xem Webhook.
forbidden	403	Token hợp lệ nhưng thiếu quyền.
account_context_mismatch	403	X-Account-Id không khớp với tài khoản của token. Thông tin về công ty hiện tại phía client đã bị lệch; hãy đọc lại từ phiên.
not_found	404	Tài nguyên không tồn tại hoặc thuộc tài khoản hay site khác. API không bao giờ phân biệt hai trường hợp này.
conflict	409	Xung đột trạng thái: khóa lạc quan, ràng buộc duy nhất, hoặc hành động không được phép ở trạng thái hiện tại (ví dụ ghi vào cuộc trò chuyện đã gộp).
idempotency_key_conflict	409	Idempotency-Key bị dùng lại với body khác.
payload_too_large	413	Body vượt quá giới hạn của nhóm endpoint này.
unsupported_media_type	415	Content-Type không đúng.
unprocessable	422	JSON hợp lệ nhưng bị một quy tắc nghiệp vụ từ chối (ví dụ khung giờ đặt lịch nằm ngoài giờ làm việc).
storage_quota_exceeded	422	Tài khoản đã đạt giới hạn lưu trữ của gói. details chứa used_bytes, quota_bytes và requested_bytes; hãy giải phóng dung lượng hoặc nâng cấp.
rate_limited	429	Hãy giảm tốc độ. Tuân theo Retry-After và details.retry_after_seconds.

Lỗi phía máy chủ

Mã	Trạng thái	Ý nghĩa và cách xử lý
internal_error	500	Lỗi không mong đợi. Thử lại một lần, sau đó liên hệ bộ phận hỗ trợ kèm request_id.
upstream_unavailable	502	Gateway hoàn toàn không kết nối được đến dịch vụ. Thử lại sau chốc lát thường sẽ thành công.
service_unavailable	503	Bảo trì theo kế hoạch hoặc circuit breaker đang mở. Thử lại sau khoảng thời gian trong header Retry-After.
ai_vendor_out_of_funds	503	Nhà cung cấp AI của bạn từ chối lệnh gọi vì lý do thanh toán (402 hoặc 429 do hết hạn mức từ nhà cung cấp). Hãy nạp thêm tiền vào tài khoản nhà cung cấp; thử lại sẽ không giúp được gì.
upstream_timeout	504	Dịch vụ không trả lời kịp thời. Thử lại khi có retry_after.

Thử lại

Thử lại 429, 502, 503, 504 và lỗi mạng với thời gian chờ tăng theo cấp số nhân, và gửi cùng Idempotency-Key khi thử lại để một thao tác ghi không bao giờ được áp dụng hai lần. Không thử lại các lỗi 4xx ngoài 429.