Chuyển tới nội dung chính

Mã trạng thái API Phổ Biến

Khi tích hợp với API của Simplize, bạn có thể nhận được các phản hồi với nhiều mã trạng thái HTTP khác nhau. Việc hiểu rõ ý nghĩa của các mã này, nguyên nhân phổ biến và cách xử lý sẽ giúp bạn gỡ lỗi và phát triển ứng dụng hiệu quả hơn.

1. Phản Hồi Thành Công (2xx Success)​

Các mã trạng thái trong dải 2xx cho biết yêu cầu đã được nhận, hiểu và chấp nhận thành công.

200 OK​

  • Mô tả: Yêu cầu đã thành công. Đây là mã trạng thái tiêu chuẩn cho phản hồi thành công của HTTP.
  • Nguyên nhân phổ biến:
    • Yêu cầu GET đã truy xuất dữ liệu thành công.
    • Yêu cầu PUT hoặc POST đã cập nhật/tạo tài nguyên thành công và trả về dữ liệu của tài nguyên đó.
    • Yêu cầu DELETE đã xóa thành công.
  • Ví dụ phản hồi: 
    {
      "status": 200,
      "message": "Success",
      "data": {
        "id": "user123",
        "name": "Nguyen Van A",
        "email": "a.nguyen@example.com"
      }
    }
  • Cách xử lý: Tiếp tục xử lý dữ liệu được trả về trong response body.

2. Lỗi Client (4xx Client Error)​

Các mã trạng thái trong dải 4xx cho biết có lỗi từ phía client (ứng dụng của bạn).

400 Bad Request​

  • Mô tả: Máy chủ không thể xử lý yêu cầu do lỗi từ phía client (ví dụ: cú pháp không hợp lệ, thiếu tham số yêu cầu, giá trị tham số không hợp lệ).
  • Nguyên nhân phổ biến:
    • JSON body không hợp lệ (lỗi cú pháp).
    • Thiếu trường dữ liệu bắt buộc trong request body hoặc query parameters.
    • Giá trị của tham số không đúng định dạng hoặc ngoài phạm vi cho phép (ví dụ: ID là chuỗi khi yêu cầu số).
  • Ví dụ phản hồi: 
    {
        "status": 400,
        "message": "Trường 'email' không đúng định dạng hoặc thiếu trường 'password'.",
    }
  • Cách xử lý:
    • Kiểm tra lại cấu trúc và định dạng của request body.
    • Đảm bảo bạn đã gửi tất cả các tham số bắt buộc với giá trị đúng kiểu và hợp lệ.
    • Đọc thông báo lỗi trong response body để biết chi tiết vấn đề.

401 Unauthorized​

  • Mô tả: Yêu cầu không được xác thực. Client phải tự xác thực để nhận được phản hồi được yêu cầu.
  • Nguyên nhân phổ biến:
    • Không gửi header X-Api-Key.
    • Header X-Api-Key trống hoặc có giá trị không hợp lệ.
    • API Key đã hết hạn hoặc đã bị thu hồi.
  • Ví dụ phản hồi: 
    {
        "status": 401,
        "message": "Yêu cầu xác thực đầy đủ để truy cập tài nguyên này",
    }
  • Cách xử lý:
    • Đảm bảo bạn đang gửi API Key hợp lệ trong header X-Api-Key.
    • Nếu bạn đang lưu API Key trong Local Storage, hãy kiểm tra xem nó có bị xóa hoặc bị ghi đè không.
    • Liên hệ với chúng tôi nếu như bạn không thể xử lý được.

403 Forbidden​

  • Mô tả: Yêu cầu đã được xác thực, nhưng client không có quyền truy cập vào tài nguyên đó hoặc không được phép thực hiện hành động đó.
  • Nguyên nhân phổ biến:
    • API Key của bạn không có đủ quyền cho hành động hoặc tài nguyên cụ thể này (ví dụ: chỉ có quyền đọc nhưng cố gắng ghi).
    • Tài nguyên bị giới hạn truy cập (ví dụ: tài nguyên của người dùng khác).
    • Địa chỉ IP của bạn bị chặn.
  • Ví dụ phản hồi: 
    {
        "status": 403,
        "message": "Bạn không có quyền truy cập vào tài nguyên này",
    }
  • Cách xử lý:
    • Kiểm tra lại quyền của API Key của bạn.
    • Đảm bảo bạn đang cố gắng truy cập tài nguyên mà bạn có quyền.
    • Nếu bạn tin rằng mình có quyền nhưng vẫn gặp lỗi, hãy liên hệ hỗ trợ.

404 Not Found​

  • Mô tả: Máy chủ không thể tìm thấy tài nguyên được yêu cầu.
  • Nguyên nhân phổ biến:
    • Đường dẫn API (URL) sai chính tả hoặc không tồn tại.
    • ID của tài nguyên không tồn tại (ví dụ: GET /users/nonexistent_id).
    • Tài nguyên đã bị xóa.
  • Ví dụ phản hồi: 
    {
        "status": 404,
        "message": "Tài nguyên không tìm thấy",
    }
  • Cách xử lý:
    • Kiểm tra lại đường dẫn API và đảm bảo nó chính xác.
    • Kiểm tra ID của tài nguyên để đảm bảo nó tồn tại và đúng.

405 Method Not Allowed​

  • Mô tả: Phương thức HTTP được sử dụng trong yêu cầu không được phép cho tài nguyên được xác định.
  • Nguyên nhân phổ biến:
    • Cố gắng POST lên một endpoint chỉ chấp nhận GET (ví dụ: gửi dữ liệu lên /users/{id} thay vì /users).
    • Sử dụng sai phương thức (ví dụ: dùng GET để xóa tài nguyên).
  • Ví dụ phản hồi: 
    {
        "status": 405,
        "message": "Phương thức HTTP không được phép cho tài nguyên này",
    }
  • Cách xử lý:
    • Kiểm tra tài liệu API để đảm bảo bạn đang sử dụng đúng phương thức HTTP cho điểm cuối đó.

3. Lỗi Máy Chủ (5xx Server Error)​

Các mã trạng thái trong dải 5xx cho biết có lỗi từ phía máy chủ API.

500 Internal Server Error​

  • Mô tả: Máy chủ đã gặp một điều kiện không mong muốn ngăn cản nó thực hiện yêu cầu. Đây là lỗi chung khi máy chủ không thể xử lý yêu cầu vì một lý do nội bộ không xác định.
  • Nguyên nhân phổ biến:
    • Lỗi lập trình ở backend API.
    • Lỗi cơ sở dữ liệu.
    • Máy chủ quá tải.
  • Ví dụ phản hồi: 
    {
        "status": 500,
        "message": "Đã xảy ra lỗi nội bộ máy chủ",
    }
  • Cách xử lý:
    • Đây là lỗi từ phía máy chủ, không phải từ phía client của bạn.
    • Bạn không thể tự khắc phục mà cần liên hệ đội ngũ hỗ trợ của Simplize. Cung cấp đầy đủ thông tin về yêu cầu của bạn và bất kỳ ID lỗi nào được trả về.

503 Service Unavailable​

  • Mô tả: Máy chủ hiện tại không thể xử lý yêu cầu do quá tải tạm thời hoặc bảo trì máy chủ.
  • Nguyên nhân phổ biến:
    • Máy chủ đang trong quá trình bảo trì.
    • Máy chủ quá tải do lưu lượng truy cập cao đột biến.
    • Các dịch vụ phụ thuộc không hoạt động.
  • Ví dụ phản hồi: 
    {
        "status": 503,
        "message": "Dịch vụ không khả dụng tạm thời, vui lòng thử lại sau",
    }
  • Cách xử lý:
    • Thử lại yêu cầu sau một khoảng thời gian ngắn.
    • Kiểm tra trang trạng thái dịch vụ của Simplize (nếu có) để biết thông tin bảo trì.

Hỗ Trợ​

Nếu bạn gặp phải bất kỳ lỗi nào không được liệt kê ở đây, hoặc cần hỗ trợ thêm, đừng ngần ngại liên hệ với đội ngũ hỗ trợ của Simplize.