Lỗi API

API thông báo lỗi bằng các mã trạng thái HTTP tiêu chuẩn và nội dung phản hồi thống nhất. Các phản hồi thành công trả về dữ liệu trực tiếp, không có wrapper bao ngoài.

Định dạng lỗi

Khi có lỗi, nội dung phản hồi là JSON object với một trường error chứa thông báo có thể đọc được:

{"error":"reaction not found"}

Hãy ưu tiên dựa vào mã trạng thái HTTP, còn văn bản error dùng cho log và gợi ý cho người dùng.

Mã trạng thái

  • 200 OK — yêu cầu thành công, trong nội dung là dữ liệu.
  • 201 Created — tài nguyên mới được tạo (một số endpoint POST).
  • 204 No Content — thành công không có nội dung (một số thao tác xóa).
  • 400 Bad Request — nội dung hoặc tham số yêu cầu không hợp lệ.
  • 401 Unauthorized — token thiếu, sai hoặc hết hạn; hoặc route không thể truy cập bằng token cá nhân.
  • 402 Payment Required — hành động bị giới hạn bởi gói cước hoặc hạn mức (ví dụ: lưu trữ media riêng yêu cầu premium).
  • 403 Forbidden — token thiếu phạm vi cần thiết cho route này.
  • 404 Not Found — tài nguyên không tìm thấy hoặc không thuộc về bạn.
  • 409 Conflict — xung đột trạng thái (ví dụ: trùng giá trị duy nhất).
  • 422 Unprocessable Entity — nội dung hợp lệ về cú pháp nhưng không vượt qua kiểm tra nghiệp vụ.
  • 429 Too Many Requests — vượt quá giới hạn yêu cầu (xem giới hạn).
  • 500 Internal Server Error — lỗi nội bộ máy chủ; hãy thử lại sau.

Cách xử lý

Coi các mã 2xx là thành công. Với 401/403 hãy kiểm tra token và phạm vi của nó. Với 4xx (trừ 429) đừng lặp lại yêu cầu mà không sửa — hãy sửa yêu cầu. Với 429 và 5xx nên thử lại với độ trễ tăng dần theo cấp số nhân.

Tiếp theo