Định dạng lỗi API và mã lỗi

Mọi phản hồi lỗi của API đều có cùng định dạng. Mã của bạn nên dựa vào mã lỗi trong trường error, không dựa vào văn bản trong message – mã luôn ổn định, còn văn bản có thể thay đổi và được dịch sang ngôn ngữ tài khoản.

#Cấu trúc của phản hồi lỗi

{
  "error": "validation_failed",
  "message": "Some of the information provided is invalid. Please check and try again.",
  "details": [
    { "field": "title", "reason": "minLength", "message": "…" }
  ],
  "request_id": "6b1f0c2e-…"
}

error

Mã máy đọc được, ví dụ not_found. Với phần lớn lỗi, mã này cũng có trong header X-Error-Code – nhưng hãy dựa vào trường trong phần thân.

message

Mô tả cho người đọc theo ngôn ngữ tài khoản: với khóa API là ngôn ngữ của chủ sở hữu không gian làm việc, với ứng dụng đã kết nối là ngôn ngữ của người đã kết nối nó. Khi không có token hợp lệ – ví dụ 401 từ bước kiểm tra token – ngôn ngữ theo Accept-Language, nếu không thì là tiếng Anh. Header Content-Language nêu ngôn ngữ.

details

Chỉ có khi cần nói thêm. Với 422 từ kiểm tra dữ liệu nhập, là một danh sách với field, reason và message cho từng vấn đề; với 422 từ logic nghiệp vụ và mọi lỗi khác, là một object, ví dụ với reason, retry_after_sec hoặc danh sách issues. Khi vượt kích thước, nó chứa field, reason và limit, và với 413 request_too_large là max_bytes và max_kb. Vì vậy hãy kiểm tra details có phải danh sách không.

request_id

ID của yêu cầu. ID này cũng có trong header X-Request-Id. Hãy gửi kèm khi liên hệ bộ phận hỗ trợ.

Ngoại lệ: phản hồi 429 rate_limited có trường retry_after_sec thay vì details; với 429 và 403 insufficient_scope, request_id không có trong phần thân. 401 từ bước kiểm tra token và 422 từ bước kiểm tra schema không có header X-Error-Code, và với bước kiểm tra schema chỉ message cấp cao nhất được dịch; các văn bản bên trong details vẫn bằng tiếng Anh. Header X-Request-Id luôn được đặt.

#Các mã quan trọng nhất

#Đọc lỗi dữ liệu nhập

Với 422 validation_failed, details liệt kê riêng từng vấn đề: field là đường dẫn của trường (với dấu gạch chéo cho object lồng nhau, ví dụ theme_config/button_style), reason là quy tắc bị vi phạm, như required, minLength, maxLength, enum hoặc additionalProperties. Với additionalProperties, message cho biết những trường nào không xác định – thường do gõ sai tên trường.

#Cách xử lý khuyến nghị trong mã

• 400, 413 và 422: đừng thử lại, hãy sửa yêu cầu
• 401 invalid_token: lấy token mới một lần rồi thử lại
• 403: đừng thử lại; hãy kiểm tra phạm vi, gói hoặc ai được phép làm việc này
• 404: kiểm tra ID; sau khi xóa thì điều này là bình thường
• 409: tải lại trạng thái và quyết định thao tác có còn cần không
• 429: đợi theo Retry-After rồi thử lại – xem Giới hạn tần suất
• 500 và 503: thử lại vài lần với khoảng nghỉ tăng dần