Lỗi

Hình dạng của một lỗi

Mọi yêu cầu thất bại đều trả về Content-Type: application/problem+json, theo RFC 9457:

HTTP/1.1 409 Conflict
Content-Type: application/problem+json
x-request-id: …

{
  "type": "STALE_VERSION",
  "title": "Conflict",
  "status": 409,
  "detail": "…",
  "request_id": "…",
  "instance": "/api/v1/entities/…/records/…",
  "extensions": { "conflict": { … } }
}

Trường nào không có giá trị — detail, field_errors, field_warnings, extensions — thì vắng hẳn khỏi thân lỗi, không bao giờ mang null.

Một 500 là lỗi không lường trước ở phía server. detail của nó chỉ là một câu chung — ý nghĩa của mã trong danh mục mã lỗi — và không bao giờ chứa chi tiết bên trong. Khi báo lỗi này, hãy gửi request_id cho bộ phận hỗ trợ: nhờ nó họ tìm lại được đúng yêu cầu của bạn.

Yêu cầu server không đọc được

Khi không đọc được chính yêu cầu — thân không phải JSON, một id sai định dạng, một tham số truy vấn lạ — server từ chối trước khi thực hiện thao tác, với một trong các mã sau:

Ví dụ, gửi GET /api/v1/instances?search=laptop — danh sách lượt chạy tìm kiếm bằng q, không có tham số search:

HTTP/1.1 400 Bad Request
Content-Type: application/problem+json

{
  "type": "UNKNOWN_QUERY_PARAMETER",
  "title": "Bad Request",
  "status": 400,
  "detail": "this operation does not accept the query parameter `search`",
  "request_id": "…",
  "instance": "/api/v1/instances",
  "field_errors": [
    { "path": "search", "message": "this operation does not accept the query parameter `search`", "rule": "unknown" }
  ]
}

• Một yêu cầu vừa có tham số lạ vừa có giá trị sai chỉ nhận UNKNOWN_QUERY_PARAMETER. Lỗi về giá trị hiện ra khi đã bỏ tham số lạ.
• Một yêu cầu không mang thông tin xác thực nhận 401 trước hết, kể cả với một đường dẫn không tồn tại: server không cho người gọi ẩn danh biết đường dẫn nào có.

Không được thấy thì trả 404

Một tài nguyên mà bạn không được phép thấy trả lời y hệt một tài nguyên không tồn tại: 404. Điều này có chủ ý. Trả 403 sẽ xác nhận rằng tài nguyên đó có tồn tại — mà với một hồ sơ nằm ngoài phạm vi của bạn, sự tồn tại ấy chính là điều phạm vi muốn giữ kín.

Vì vậy, khi nhận 404 cho một id mà bạn chắc là đúng, hãy kiểm tra quyền của khóa bằng GET /caller và các lượt cấp quyền trên thực thể, trước khi kết luận là nó đã bị xóa.

Khi nào nên thử lại