Reason code ổn định
Error code ổn định được dùng trong logic phía client, reporting và tự động phân loại yêu cầu hỗ trợ.
Documentation / API Errors
Xử lý API error
Một model thống nhất cho response, error code, lỗi tạm thời, kết quả chưa xác định, chẩn đoán và khôi phục an toàn trong các tích hợp iGaming.
HTTP
kết quả request
Mã
nguyên nhân rõ ràng
Retry
hành động an toàn
Truy vết
chẩn đoán request
Chu trình xử lý lỗi
Từ API response đến khôi phục
01
Xác định loại kết quả
Kiểm tra HTTP status, reason code, loại lỗi và trạng thái giao dịch.
02
Lưu dữ liệu để điều tra
Ghi lại request ID và operation ID, endpoint, thời gian, provider reference và các tham số an toàn.
03
Chọn hành động an toàn
Sửa dữ liệu, dừng giao dịch, retry sau một khoảng trễ hoặc kiểm tra trạng thái hiện tại.
04
Khôi phục và kiểm tra
Ngăn duplicate, đối soát kết quả, thông báo cho các team phụ trách và xử lý nguyên nhân gốc.
Tổng quan
Lỗi phải giải thích nguyên nhân và bước xử lý tiếp theo
Chỉ trả về HTTP 400 hoặc 500 là chưa đủ. Một API đáng tin cậy phải trả về reason code ổn định, liên kết response với request ID và cho biết rõ cần sửa dữ liệu, dừng giao dịch, retry request hay kiểm tra riêng trạng thái.
Hành động có thể dự đoán
Loại lỗi cho biết request có thể retry hay không và cần thay đổi dữ liệu nào.
Liên kết phục vụ chẩn đoán
Request ID, operation ID và provider ID liên kết client log với hệ thống nội bộ và support.
Cấu trúc lỗi
Cấu trúc error response được khuyến nghị
Response nên gọn, ổn định và phù hợp cho xử lý tự động mà không để lộ triển khai nội bộ hoặc dữ liệu nhạy cảm.
Error code
Mã định danh ổn định cho nguyên nhân, không thay đổi khi nội dung giải thích được chỉnh sửa.
Mô tả
Giải thích ngắn gọn, an toàn, không chứa code nội bộ, database query, secret hoặc chi tiết không cần thiết.
Request ID
Mã định danh duy nhất để tìm giao dịch trong log và liên hệ support.
Dữ liệu bổ sung
Status được phép, limit, trạng thái hiện tại hoặc lý do từ chối an toàn.
Có thể retry
Dấu hiệu rõ ràng của lỗi tạm thời, nhưng không loại bỏ cơ chế chống duplicate cho giao dịch.
Khoảng chờ trước khi retry
Khoảng trễ được khuyến nghị tính bằng giây hoặc HTTP header dùng cho rate limiting và trạng thái tạm thời không khả dụng.
Lỗi theo field
Danh sách field có vấn đề kèm reason code, đường dẫn giá trị và giải thích an toàn.
Tham chiếu documentation
Link cố định hoặc mã mục mô tả nguyên nhân và cách khắc phục.
Các loại lỗi
Các loại lỗi chính
HTTP status cho biết nhóm kết quả chung, còn code nội bộ xác định nguyên nhân cụ thể và hành động được phép.
Lỗi validation dữ liệu đầu vào
Sai format, thiếu field bắt buộc, giá trị không được hỗ trợ, độ chính xác số tiền không hợp lệ hoặc cấu trúc request sai.
Lỗi authentication
Thiếu, hết hạn hoặc không hợp lệ: token, API key, signature, request timestamp hoặc nonce.
Không đủ quyền
Client đã được nhận diện nhưng không có role, brand, market hoặc permission cần thiết cho hành động.
Không tìm thấy object
Player, payment, round, KYC check, provider hoặc object khác không tồn tại hoặc không khả dụng với client.
Xung đột trạng thái
Version hoặc trạng thái của object đã thay đổi, hoặc operation ID đã được dùng với tham số khác.
Vi phạm business rule
Không đủ số dư, vượt limit, player bị khóa, market bị cấm hoặc chuyển status không hợp lệ.
Quá nhiều request
Đã vượt số lượng request được phép cho client, method, role hoặc giao dịch quan trọng.
Provider không khả dụng
Dịch vụ bên ngoài không khả dụng, phản hồi chậm hoặc tạm thời không nhận giao dịch.
Lỗi nội bộ
Lỗi platform ngoài dự kiến, không để lộ chi tiết nội bộ nhưng có mã định danh phục vụ chẩn đoán.
Retry và khôi phục
Retry request và kết quả chưa xác định
Chỉ retry an toàn sau khi xác định loại lỗi và kiểm tra xem giao dịch ban đầu có thể đã hoàn tất hay chưa.
01
Kiểm tra có được phép retry không
Lỗi dữ liệu, quyền và business rule thường yêu cầu sửa request thay vì gửi lại.
02
Giữ nguyên operation key
Retry một giao dịch tài chính, gaming hoặc giao dịch quan trọng khác không được tạo ra kết quả mới.
03
Tăng khoảng trễ giữa các lần thử
Khoảng chờ tăng dần, tuân theo thời gian server cung cấp và giới hạn tổng số lần thử.
04
Dừng và chuyển sang review
Khi đã hết số lần thử, giao dịch được ghi nhận là chưa hoàn tất và chuyển sang manual review hoặc đối soát.
Không có response không có nghĩa là giao dịch thất bại
Nếu kết nối bị ngắt sau khi request đã gửi, kết quả có thể vẫn chưa xác định. Trước khi retry, hãy kiểm tra trạng thái bằng operation ID hoặc chờ notification đáng tin cậy.
Chẩn đoán và kiểm soát
Log, mã định danh, metric và alert
Chẩn đoán phải tái dựng được đường đi của request giữa platform, adapter và provider bên ngoài mà không lưu dữ liệu nhạy cảm không cần thiết.
Ngữ cảnh để điều tra
Request ID, correlation ID, operation ID và external provider ID.
Endpoint, HTTP method, environment, client, thời gian và thời lượng response.
HTTP status, error code, số lần thử và trạng thái cuối.
Các field nhạy cảm đã được che, header an toàn và kết quả kiểm tra signature.
Monitoring và alert
Tỷ lệ lỗi theo method, provider, client và nhóm nguyên nhân.
Mức tăng của response chậm, lỗi HTTP 5xx, signature không hợp lệ và các sự kiện rate limit.
Số lần retry, giao dịch có kết quả chưa xác định và task khôi phục.
Alert với threshold, owner và escalation rule.
Testing
Cần kiểm tra gì trong test environment
Test environment phải mô phỏng được mọi loại lỗi quan trọng và xác nhận hành vi đúng của client, retry và cơ chế kiểm soát.
Lỗi validation dữ liệu đầu vào
Thiếu field, sai type, giá trị không được hỗ trợ, độ chính xác số tiền và nhiều lỗi cùng lúc.
Access và permission
Key không hợp lệ, token hết hạn, signature sai, role không được phép, IP bị chặn và nonce bị tái sử dụng.
Không có response và kết quả chưa xác định
Mất kết nối trước khi gửi, sau khi giao dịch đã được nhận và trong lúc nhận response cuối.
Rate limiting
HTTP 429, khoảng chờ được khuyến nghị, request đồng thời và khôi phục sau khi limit hết hiệu lực.
Lỗi provider
Không khả dụng, bảo trì, response không hợp lệ, notification bị trễ và status mâu thuẫn.
Retry và dừng bảo vệ
Giới hạn số lần thử, tăng khoảng chờ, tạm dừng request, khôi phục có kiểm soát và manual escalation.
Checklist trước launch
Tích hợp production chỉ launch sau khi đã kiểm tra cấu trúc lỗi, hành vi client, bảo vệ duplicate và chẩn đoán.
Tất cả lỗi đều trả về reason code ổn định và request ID.
Chi tiết lỗi không làm lộ secret hoặc triển khai nội bộ.
Các loại lỗi tạm thời và lỗi lâu dài được mô tả trong documentation.
Khi retry giao dịch quan trọng, sử dụng cùng một idempotency key.
Kết quả chưa xác định được xử lý bằng cách kiểm tra trạng thái hoặc nhận notification đáng tin cậy.
Đã cấu hình log, metric, alert, recovery queue và escalation rule.
Cần chuẩn hóa API error?
Gửi cho chúng tôi HTTP response hiện tại, error code, retry rule và các scenario có vấn đề. APIACE sẽ giúp xác định error model thống nhất, cơ chế khôi phục an toàn và kiểm soát.