Xử lý lỗi & Lịch trình Retry

Xử lý lỗi webhook HiTechCloud Pay: cơ chế gửi lại (retry) tự động khi endpoint gặp sự cố, lịch trình thử lại và cách xử lý các mã lỗi thường gặp.

Xem Markdown

Khi máy chủ webhook của bạn gặp sự cố (quá tải, mất kết nối, timeout hoặc phản hồi mã lỗi 5xx/4xx), HiTechCloud Pay sẽ tự động kích hoạt cơ chế gửi lại (Retry) thông minh theo khoảng thời gian lũy tiến.

Lịch trình Retry tự động

Lần gửiThời gian sau lần gửi trướcTrạng thái
Lần 1 (Gốc)Tức thì khi phát sinh giao dịchBan đầu
Lần 2Sau 1 phútThử lại lần 1
Lần 3Sau 5 phútThử lại lần 2
Lần 4Sau 15 phútThử lại lần 3
Lần 5Sau 30 phútThử lại lần 4
Lần 6Sau 1 giờThử lại lần 5
Lần 7Sau 2 giờThử lại lần 6
Lần 8Sau 6 giờThử lại lần 7
Lần 9Sau 12 giờThử lại lần 8
Lần 10Sau 24 giờLần thử cuối cùng trước khi chuyển sang trạng thái Thất bại

Các nguyên nhân gây lỗi phổ biến & Cách khắc phục

Mã lỗi / Sự cốNguyên nhânCách khắc phục
HTTP 404 Not FoundSai đường dẫn URL webhook hoặc router trên server chưa đăng ký routeKiểm tra lại URL webhook trên my.hitechcloud.vn
HTTP 401 UnauthorizedXác thực HMAC hoặc API Key thất bạiKiểm tra lại SECRET_KEY hoặc cách đọc raw body
HTTP 500 Internal Server ErrorLỗi mã nguồn máy chủ (ví dụ: lỗi kết nối CSDL, crash PHP/Node)Kiểm tra file error log trên server của bạn
Connection Timeout (> 30s)Xử lý nghiệp vụ nặng (gửi email, gọi API bên thứ ba) ngay trong luồng webhookChuyển các tác vụ nặng vào Message Queue (Redis / RabbitMQ)

Bắn lại Webhook thủ công (Manual Replay)

Trong trường hợp máy chủ của bạn bị mất điện hoặc bảo trì kéo dài khiến tất cả các lần retry tự động đều thất bại, bạn có thể truy cập https://my.hitechcloud.vn → Webhooks → chọn giao dịch bị lỗi và nhấn nút Gửi lại (Replay) để kích hoạt gửi lại ngay lập tức.

Sau khi hết 10 lần retry mà endpoint vẫn không phản hồi thành công, giao dịch sẽ được đánh dấu 'Thất bại'. Bạn vẫn có thể vào trang Quản lý Webhooks trên my.hitechcloud.vn để bấm nút 'Gửi lại thủ công' bất kỳ lúc nào.