Lỗi (problem+json)

Khi một yêu cầu thất bại, API trả mã trạng thái HTTP phù hợp cùng nội dung theo RFC 9457 với kiểu application/problem+json. Nhờ định dạng thống nhất, bạn xử lý mọi lỗi bằng cùng một đoạn mã.

Cấu trúc

{
  "type": "https://api.hoadon.pro/problems/validation_failed",
  "title": "Dữ liệu không hợp lệ",
  "status": 422,
  "code": "validation_failed",
  "detail": "Một hoặc nhiều trường không hợp lệ.",
  "request_id": "req_01J9ZQ8KABCDEF",
  "errors": [
    { "field": "org_id", "code": "required", "message": "Thiếu org_id." }
  ]
}

Ví dụ trên minh hoạ hình dạng của phản hồi; giá trị type, code và thông điệp cụ thể của từng lỗi xem ở Danh mục mã lỗi.

Trường	Ý nghĩa
type	Định danh loại lỗi, dạng URI.
title	Tiêu đề ngắn của loại lỗi.
status	Mã trạng thái HTTP, trùng với mã của phản hồi.
code	Mã lỗi ổn định, dùng để xử lý trong mã nguồn.
detail	Mô tả chi tiết cho lần gọi này. Dành cho người đọc.
request_id	Mã của yêu cầu. Gửi kèm khi liên hệ hỗ trợ.
errors	Chỉ có khi lỗi liên quan tới từng trường (kiểm tra dữ liệu): mảng {field, code, message}.

Cách xử lý

• Dựa vào code, không dựa vào title, detail hay message. Câu chữ có thể được chỉnh sửa; code ổn định.
• Ghi lại request_id trong nhật ký của bạn. Đây là cách nhanh nhất để đội hỗ trợ tìm đúng yêu cầu.
• Phân loại theo status: lỗi 4xx do yêu cầu (sửa rồi mới gọi lại), lỗi 5xx do phía hoadon.pro (thử lại có chờ, với thao tác ghi dùng Idempotency).
• Với lỗi theo trường, hiển thị errors[].message cạnh đúng ô nhập dựa vào errors[].field.
• 404 cũng được dùng khi tài nguyên tồn tại nhưng khoá của bạn không có quyền; API không phân biệt hai trường hợp.

Ví dụ xử lý

const res = await fetch(url, { headers });
if (!res.ok) {
  const problem = await res.json();
  console.error(problem.code, problem.request_id);
  if (res.status >= 500) {
    // thử lại có chờ
  }
  throw new Error(problem.code);
}