Khắc phục sự cố

Mọi sự cố trong Averosi đều rơi vào một trong vài nhóm: endpoint từ chối request, job không bao giờ chạy, hoặc job đã chạy nhưng đích đến từ chối nhận. Trang này đi từ triệu chứng → nguyên nhân → cách khắc phục.

Bảng tra nhanh theo triệu chứng

Checklist khi "một lead không về đích"

Kiểm tra lần lượt theo thứ tự sau — mỗi bước loại trừ một công đoạn trong pipeline.

1. Đích đến có đang Active không? Mở Kết nối. Một connection phải có nhãn Active (trạng thái connected) mới nhận được lead. Connection chưa cấu hình hoặc không active sẽ bị bỏ qua âm thầm khi fan-out.
2. Event đã thực sự được ingest chưa? Mở Giám sát và tìm dòng lead_created ở phần Event Stream, đúng khoảng thời gian bạn gửi. Nếu không thấy, nghĩa là bản thân lệnh gọi webhook đã thất bại — đối chiếu mã phản hồi với bảng ở trên.
3. Job đã được xử lý chưa? Một event vừa ingest thường thoát khỏi trạng thái queued trong vòng một, hai phút. Nếu nó kẹt ở queued lâu hơn nhiều so với vậy, xem job kẹt ở trạng thái queued bên dưới.
4. Job có bị failed hay dead-letter không? Xem bảng Delivery Jobs trên Giám sát. Job failed sẽ tự thử lại theo backoff; job dead thì không tự thử lại nữa — xem job bị dead-letter.

Các lỗi phản hồi từ webhook

400 — Invalid JSON body

Request body không parse được thành JSON — thường do form hoặc nền tảng gửi dữ liệu dạng multipart/form-data thay vì JSON, hoặc gửi body rỗng.

Cách sửa: gửi kèm header Content-Type: application/json với body JSON hợp lệ. Xem Webhook & API để biết đúng cấu trúc payload và một đoạn mã form mẫu.

422 — Payload failed validation

Body parse được thành JSON nhưng không khớp schema của webhook đầu vào (thiếu field bắt buộc, sai kiểu dữ liệu), hoặc endpoint được resolve không có attribution config đang active. Phản hồi có kèm mảng issues từ schema — đọc nó, nó chỉ đích danh field nào bị lỗi.

Cách sửa: đối chiếu payload của bạn với cấu trúc đã tài liệu hóa ở Webhook & API và sửa (các) field bị lỗi. Nếu lỗi liên quan tới attribution config chứ không phải field cụ thể, mở Cài đặt và xác nhận endpoint đã gắn một attribution config đang active.

503 — Server chưa được cấu hình

App chưa được cấu hình xong nên không đọc/ghi được dữ liệu gì cả. Thường bạn cũng sẽ thấy trạng thái rỗng ở khắp nơi trong app (Kết nối, Giám sát, Cài đặt) trong lúc này.

Cách sửa: đây là vấn đề cấu hình phía server, không thể tự sửa từ giao diện — liên hệ quản trị viên để hoàn tất cấu hình app.

Job kẹt ở trạng thái "queued"

Job nằm ở trạng thái queued nghĩa là nó đã được tạo nhưng chưa được xử lý. Bình thường nó sẽ thoát khỏi trạng thái này trong vòng một, hai phút sau khi event đến.

Job bị dead-letter

Một job chuyển sang dead — và ngừng thử lại — khi đích đến liên tục từ chối với lỗi không thể thử lại, hoặc khi đã dùng hết số lần thử. Nguyên nhân phổ biến nhất là đích đến trả về liên tiếp lỗi 4xx (token sai, quyền truy cập bị thu hồi, sai chat/sheet id); một job dead cũng tạo ra một event chuẩn hóa sync_failed để hiển thị trên Event Stream.

Cách sửa: mở job đó trên Giám sát và đọc last_error — đó là thông báo lỗi gốc từ đích đến. Sau đó vào Kết nối, kiểm tra lại thông tin đăng nhập của đích đến đó (bot token, chat id, access token, spreadsheet id, service-account key), bấm Kiểm tra, rồi kết nối lại. Sau khi sửa xong, retry job đó từ Observability — nó không tự chạy lại.

Trang liên quan

• Webhook & API — cấu trúc payload, mã phản hồi, và đoạn mã form test.
• Giám sát — event stream, delivery jobs, và thống kê sức khỏe hệ thống.
• Kết nối — kết nối và kiểm tra từng đích đến.