Khắc phục các lỗi thường gặp khi gọi API (422, 500, 401)

Khi tích hợp với ABOT REST API, lập trình viên hoặc chuyên viên kỹ thuật có thể gặp một số mã lỗi phổ biến. Dưới đây là nguyên nhân chi tiết và cách khắc phục dứt điểm từng lỗi.

---

1. Lỗi 422 Unprocessable Entity (phone/email: This field must be unique.)

Biểu hiện:

Khi gọi POST /api/contacts/new để thêm liên hệ mới, hệ thống trả về mã lỗi 422:

{
  "errors": [
    {
      "code": 422,
      "message": "phone: This field must be unique.",
      "details": {
        "phone": [
          "This field must be unique."
        ]
      }
    }
  ]
}

Nguyên nhân:

• Trường phone (hoặc email) đang được cấu hình là Unique Identifier (Định danh duy nhất) trong ABOT (is_unique_identifer = 1).

• Từ phiên bản Mautic 5.0 trở lên (áp dụng trên ABOT 7.x), bộ kiểm định UniqueCustomFieldValidator kiểm tra nghiêm ngặt: Nếu số điện thoại hoặc email gửi lên đã tồn tại trên một contact khác trong CSDL, API tạo mới (/new) sẽ chặn lại để tránh ghi đè sai lệch dữ liệu.

Cách xử lý:

• Cách 1 (Khuyên dùng khi tích hợp): Chuyển sang dùng API Batch:

  POST /api/contacts/batch/new

  Hệ thống sẽ tự động cập nhật (merge) thông tin mới vào contact cũ thay vì báo lỗi 422.

• Cách 2: Tắt cờ duy nhất cho trường phone (nếu mô hình kinh doanh B2B cho phép nhiều người dùng chung số điện thoại công ty):

  • Vào Cài đặt ➡️ Custom Fields ➡️ Sửa trường Phone ➡️ Chọn Unique Identifier: No ➡️ Lưu lại.

---

2. Lỗi 500 Internal Server Error (Argument #1 ($params) must be of type array, string given)

Biểu hiện:

Khi gọi POST /api/contacts/batch/new, hệ thống trả về mã lỗi 500:

TypeError: Mautic\LeadBundle\Controller\Api\LeadApiController::getNewEntity(): Argument #1 ($params) must be of type array, string given

Nguyên nhân:

API Batch yêu cầu dữ liệu gửi lên phải là một Mảng các đối tượng JSON (Array of Objects), bắt đầu bằng [ và kết thúc bằng ]. Nếu bạn gửi nhầm định dạng một đối tượng đơn lẻ { ... }:

{
  "email": "[email protected]",
  "phone": "0912345678"
}

PHP 8.4 sẽ đọc key "email" và value "[email protected]" (chuỗi string) rồi truyền vào hàm xử lý kiểu mảng, dẫn đến xung đột kiểu dữ liệu (TypeError).

Cách xử lý:

Luôn bọc dữ liệu gửi lên trong cặp dấu ngoặc vuông [ ] (kể cả khi chỉ gửi 1 contact):

[
  {
    "email": "[email protected]",
    "phone": "0912345678"
  }
]

---

3. Lỗi 401 Unauthorized (Authentication required)

Biểu hiện:

API từ chối xử lý và báo chưa được cấp quyền:

{
  "errors": [
    {
      "code": 401,
      "message": "Authentication required"
    }
  ]
}

Nguyên nhân & Cách xử lý:

1. Chưa bật Basic Auth: Vào Cài đặt ➡️ Configuration ➡️ API Settings ➡️ Đảm bảo cả hai mục API enabled và Enable HTTP basic auth đều được chuyển sang Yes.

2. Sai chuỗi Base64: Chuỗi xác thực trong header Authorization: Basic <base64> phải được tạo từ định dạng username:password (ví dụ admin_ncnetwork:MatKhau123!).

3. Phân quyền tài khoản: Tài khoản được dùng để gọi API phải thuộc nhóm vai trò (Role) có quyền quản trị hoặc có quyền quản lý API trong ABOT.

---

4. Lỗi 400 Bad Request (Invalid json message received)

Biểu hiện:

{
  "errors": [
    {
      "code": 400,
      "message": "Invalid json message received"
    }
  ]
}

Nguyên nhân:

Chuỗi JSON trong body bị sai cú pháp (thiếu dấu phẩy, thừa dấu ngoặc kép, ký tự escape không hợp lệ hoặc thiếu header Content-Type: application/json).

Cách xử lý:

• Đảm bảo header có: Content-Type: application/json.

• Kiểm tra cú pháp JSON hợp lệ qua jsonlint.com trước khi gửi.