Mã lỗi & Xử lý lỗi

Mã lỗi HiTechCloud Omnichannel: danh sách mã HTTP, mã lỗi chuỗi và cách xử lý khi gọi API hội thoại đa kênh gặp lỗi.

Xem Markdown

Khi một yêu cầu không thành công, Omnichannel API trả về mã HTTP phù hợp cùng Envelope lỗi có status: error, code và message. Hãy xử lý logic dựa trên code (ổn định) thay vì message (có thể đổi).

Mã trạng thái HTTP

HTTPÝ nghĩa
200 OKThành công
201 CreatedTạo mới thành công (gửi tin, tạo đơn, đăng ký webhook)
400 Bad RequestTham số không hợp lệ
401 UnauthorizedThiếu hoặc sai Access Token
403 ForbiddenToken không đủ scope hoặc không có quyền với kênh
404 Not FoundKhông tìm thấy tài nguyên theo id
409 ConflictXung đột, ví dụ gửi trùng idempotency_key
422 Unprocessable EntityDữ liệu không qua được kiểm tra nghiệp vụ
429 Too Many RequestsVượt giới hạn tần suất
500 Internal Server ErrorLỗi phía máy chủ, hãy thử lại sau

Mã lỗi chuỗi (code)

codeHTTPMô tả
UNAUTHORIZED401Token không hợp lệ hoặc đã hết hạn
INSUFFICIENT_SCOPE403Token thiếu scope cần thiết
CHANNEL_NOT_CONNECTED403Kênh chưa kết nối hoặc đã mất quyền truy cập
NOT_FOUND404id hội thoại / khách / đơn không tồn tại
VALIDATION_ERROR400/422Tham số hoặc payload sai định dạng
MESSAGING_WINDOW_CLOSED422Ngoài cửa sổ nhắn tin cho phép của nền tảng
DUPLICATE_REQUEST409Trùng idempotency_key của một tin đã gửi
TOO_MANY_REQUESTS429Vượt giới hạn tần suất, xem Retry-After
INTERNAL_ERROR500Lỗi không mong muốn phía hệ thống
Ví dụ lỗi ngoài cửa sổ nhắn tin
{
  "status": "error",
  "code": "MESSAGING_WINDOW_CLOSED",
  "message": "Hội thoại đã ngoài cửa sổ 24 giờ của Facebook. Hãy dùng mẫu tin được phép hoặc chờ khách nhắn lại."
}
Xử lý lỗi gọn trong TypeScript
async function callOmni(path: string, token: string) {
  const res = await fetch(`https://omni.hitechcloud.vn${path}`, {
    headers: { Authorization: `Bearer ${token}` },
  });
  const body = await res.json();
  if (body.status === "error") {
    if (body.code === "TOO_MANY_REQUESTS") {
      const wait = Number(res.headers.get("Retry-After") ?? "5");
      throw new Error(`Rate limit, thử lại sau ${wait}s`);
    }
    throw new Error(`[${body.code}] ${body.message}`);
  }
  return body.data;
}
Với 500 và 429, hãy thử lại có độ trễ tăng dần (exponential backoff). Với 400, 401, 403, 404, 422, việc thử lại thường vô ích — cần sửa request.