> For the complete documentation index, see [llms.txt](https://docs.abot.vn/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.abot.vn/cam-nang-xu-ly-su-co-troubleshooting/cac-loi-thuong-gap-khi-goi-api.md).

# 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:

```json
{
  "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:

  ```http
  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ẻ `{ ... }`:

```json
{
  "email": "abc@example.com",
  "phone": "0912345678"
}
```

PHP 8.4 sẽ đọc key `"email"` và value `"abc@example.com"` (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):

```json
[
  {
    "email": "abc@example.com",
    "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:

```json
{
  "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:

```json
{
  "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](https://jsonlint.com/) trước khi gửi.