Lỗi và mã lỗi

Định dạng lỗi

{
  "error": {
    "code": "INVALID_AMOUNT",
    "message": "Số tiền phải là số nguyên từ 1.000 đến 500.000.000 VND."
  }
}

• code: mã lỗi viết hoa, cố định. Hệ thống của bạn so khớp theo chuỗi này.
• message: câu tiếng Việt giải thích lỗi và việc cần làm. Câu chữ có thể được sửa cho rõ hơn, nên đừng so khớp theo message.

Mã HTTP

Mã lỗi

Danh sách này có thể có thêm mã mới khi API có thêm endpoint. Gặp mã chưa biết thì xử lý theo mã HTTP: 4xx là lỗi của request, 5xx là lỗi tạm thời.

Khi nào nên retry

• Nên retry: 429, 500 và lỗi mạng (timeout, mất kết nối). Đợi lâu dần giữa các lần gửi (backoff), có chút ngẫu nhiên.
• Không retry: các lỗi 4xx còn lại. Gửi lại y nguyên vẫn nhận đúng lỗi đó.

const res = await fetch(url, options);
const data = await res.json();

if (!res.ok) {
  const { code, message } = data.error;
  if (res.status === 429 || res.status >= 500) {
    // Lỗi tạm thời: đợi rồi gửi lại (xem Giới hạn tần suất)
  } else if (code === "NO_BANK_ACCOUNT") {
    // Báo người quản trị liên kết tài khoản ngân hàng
  } else {
    // Lỗi do request: sửa request, không retry
    throw new Error(`${code}: ${message}`);
  }
}