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.
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 OK | Thành công |
201 Created | Tạo mới thành công (gửi tin, tạo đơn, đăng ký webhook) |
400 Bad Request | Tham số không hợp lệ |
401 Unauthorized | Thiếu hoặc sai Access Token |
403 Forbidden | Token không đủ scope hoặc không có quyền với kênh |
404 Not Found | Không tìm thấy tài nguyên theo id |
409 Conflict | Xung đột, ví dụ gửi trùng idempotency_key |
422 Unprocessable Entity | Dữ liệu không qua được kiểm tra nghiệp vụ |
429 Too Many Requests | Vượt giới hạn tần suất |
500 Internal Server Error | Lỗi phía máy chủ, hãy thử lại sau |
Mã lỗi chuỗi (code)
| code | HTTP | Mô tả |
|---|---|---|
UNAUTHORIZED | 401 | Token không hợp lệ hoặc đã hết hạn |
INSUFFICIENT_SCOPE | 403 | Token thiếu scope cần thiết |
CHANNEL_NOT_CONNECTED | 403 | Kênh chưa kết nối hoặc đã mất quyền truy cập |
NOT_FOUND | 404 | id hội thoại / khách / đơn không tồn tại |
VALIDATION_ERROR | 400/422 | Tham số hoặc payload sai định dạng |
MESSAGING_WINDOW_CLOSED | 422 | Ngoài cửa sổ nhắn tin cho phép của nền tảng |
DUPLICATE_REQUEST | 409 | Trùng idempotency_key của một tin đã gửi |
TOO_MANY_REQUESTS | 429 | Vượt giới hạn tần suất, xem Retry-After |
INTERNAL_ERROR | 500 | Lỗ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.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 OK | Thành công |
201 Created | Tạo mới thành công (gửi tin, tạo đơn, đăng ký webhook) |
400 Bad Request | Tham số không hợp lệ |
401 Unauthorized | Thiếu hoặc sai Access Token |
403 Forbidden | Token không đủ scope hoặc không có quyền với kênh |
404 Not Found | Không tìm thấy tài nguyên theo id |
409 Conflict | Xung đột, ví dụ gửi trùng idempotency_key |
422 Unprocessable Entity | Dữ liệu không qua được kiểm tra nghiệp vụ |
429 Too Many Requests | Vượt giới hạn tần suất |
500 Internal Server Error | Lỗi phía máy chủ, hãy thử lại sau |
Mã lỗi chuỗi (code)
| code | HTTP | Mô tả |
|---|---|---|
UNAUTHORIZED | 401 | Token không hợp lệ hoặc đã hết hạn |
INSUFFICIENT_SCOPE | 403 | Token thiếu scope cần thiết |
CHANNEL_NOT_CONNECTED | 403 | Kênh chưa kết nối hoặc đã mất quyền truy cập |
NOT_FOUND | 404 | id hội thoại / khách / đơn không tồn tại |
VALIDATION_ERROR | 400/422 | Tham số hoặc payload sai định dạng |
MESSAGING_WINDOW_CLOSED | 422 | Ngoài cửa sổ nhắn tin cho phép của nền tảng |
DUPLICATE_REQUEST | 409 | Trùng idempotency_key của một tin đã gửi |
TOO_MANY_REQUESTS | 429 | Vượt giới hạn tần suất, xem Retry-After |
INTERNAL_ERROR | 500 | Lỗi không mong muốn phía hệ thống |
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.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;
}