> ## Documentation Index
> Fetch the complete documentation index at: https://hoalulab.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Error Code

## Error Response

DNSE OpenAPI trả về lỗi thông qua hai thành phần: `HTTP status code` ở response header và `code` ở response body. Tùy loại lỗi, response có thể kèm thêm `status` và `message` theo từng trường hợp cụ thể tương ứng.

Ví dụ:

```json lines theme={null}
{
  "status": "error",
  "code": "OA-400",
  "message": "Authorization field missing, malformed or invalid"
}
```

```json lines theme={null}
{
  "code": "INVALID_MARKET_TYPE"
}
```

```json lines theme={null}
{
  "success": false,
  "code": "FORBIDDEN",
  "message": "You do not have access to this account"
}
```

```json lines theme={null}
{
  "status": 400,
  "code": "RESOURCE_NOT_FOUND",
  "message": "Not found deal by id=..."
}
```

Luôn đọc trường `code` để xác định nguyên nhân và tra cứu hướng xử lý.

## Error Codes

### OpenAPI Errors

| HTTP status | Code | Meaning | Description | Recommended Action |
| - | - | - | - | - |
| 400 | OA-400 | Bad request | Request không hợp lệ — thiếu thông tin bắt buộc, sai tham số, sai format, thiếu trường body | Kiểm tra lại tham số và định dạng dữ liệu theo tài liệu API |
| 401 | OA-401 | Unauthorized | API Key không hợp lệ hoặc đã bị xóa | Kiểm tra API Key còn hiệu lực và được truyền đúng trong header |
| 403 | OA-403 | Forbidden | Không có quyền thực hiện yêu cầu — bị từ chối hoặc tài khoản thiếu quyền | Đảm bảo API Key được cấp đúng permission cho chức năng này |
| 404 | OA-404 | Not found | Endpoint không tồn tại hoặc tài nguyên không tìm thấy | Kiểm tra lại đường dẫn endpoint và thông tin tài nguyên |
| 405 | OA-405 | Method not allowed | HTTP Method không được hỗ trợ cho endpoint này | Kiểm tra lại HTTP Method theo tài liệu API |
| 422 | OA-422 | Unprocessable entity | Request đúng định dạng nhưng không thỏa mãn điều kiện nghiệp vụ | Kiểm tra dữ liệu nghiệp vụ trước khi gửi lại request |
| 429 | OA-429 | Too Many Requests | Vượt quá giới hạn số lượng request | Kiểm tra lại tần suất nằm trong giới hạn giờ và ngày theo từng Endpoint |
| 500 | OA-500 | Internal server error | Lỗi hệ thống tạm thời | Thử lại sau. Nếu lỗi tiếp tục, liên hệ bộ phận hỗ trợ |
| 503 | OA-503 | Service unavailable | Dịch vụ tạm thời không khả dụng | Thử lại sau |

### Validation Errors

| Code | Description | Recommended Action |
| - | - | - |
| ACCOUNT\_MISSING | Thiếu thông tin tài khoản | Truyền thông tin tiểu khoản giao dịch hợp lệ |
| SYMBOL\_MISSING | Thiếu mã chứng khoán | Truyền mã chứng khoán trong request |
| INPUT\_MISSING | Thiếu dữ liệu đầu vào | Kiểm tra và truyền đầy đủ các trường bắt buộc |
| INPUT\_INVALID | Dữ liệu đầu vào không hợp lệ | Kiểm tra lại giá trị các trường theo tài liệu API |
| INPUT\_FORMAT\_INVALID | Sai định dạng dữ liệu | Kiểm tra kiểu dữ liệu và định dạng các trường |
| INVALID\_ORDER\_TYPE | Loại lệnh không hợp lệ | Kiểm tra giá trị `orderType` theo danh sách được hỗ trợ |
| INVALID\_ORDER\_SIDE | Chiều lệnh không hợp lệ | Kiểm tra giá trị `side` (NB/NS) |
| INVALID\_SYMBOL | Mã chứng khoán không hợp lệ | Kiểm tra mã chứng khoán trước khi gửi request |
| INVALID\_PRICE | Giá đặt không hợp lệ | Kiểm tra giá nằm trong biên độ trần/sàn của mã |
| INVALID\_PRICE\_LOT | Giá không đúng bước giá | Điều chỉnh giá theo bước giá của sàn giao dịch |
| INVALID\_QUANTITY | Khối lượng không hợp lệ | Kiểm tra khối lượng lớn hơn 0 và thỏa mãn điều kiện mua/bán |
| INVALID\_QUANTITY\_LOT | Khối lượng không đúng quy định lô | Điều chỉnh khối lượng theo quy định lô của sàn |
| PRICE\_MUST\_LESS\_THAN\_OR\_EQUAL\_TO\_CEILING\_PRICE | Giá đặt vượt giá trần | Giảm giá xuống không vượt quá giá trần |
| PRICE\_MUST\_GREATER\_THAN\_OR\_EQUAL\_TO\_FLOOR\_PRICE | Giá đặt thấp hơn giá sàn | Tăng giá lên không thấp hơn giá sàn |

### Trading Session Errors

| Code | Description | Recommended Action |
| - | - | - |
| CAN\_NOT\_PLACE\_ORDER\_ON\_THIS\_SESSION | Không thể đặt lệnh trong phiên này | Thực hiện trong phiên giao dịch phù hợp |
| CAN\_NOT\_PLACE\_ORDER\_WITH\_THAT\_ORDER\_TYPE\_ON\_ATO\_SESSION | Loại lệnh không hỗ trợ trong phiên ATO | Đổi loại lệnh sang LO/ATO hoặc thực hiện trong phiên phù hợp |
| CAN\_NOT\_PLACE\_ORDER\_WITH\_THAT\_ORDER\_TYPE\_ON\_ATC\_SESSION | Loại lệnh không hỗ trợ trong phiên ATC | Đổi loại lệnh sang LO/ATC hoặc thực hiện trong phiên phù hợp |
| INVALID\_ORDER\_TYPE\_FOR\_THIS\_SESSION | Loại lệnh không hợp lệ trong phiên hiện tại | Đổi loại lệnh hoặc đặt lại trong phiên phù hợp |
| INVALID\_TRADING\_SESSION | Phiên giao dịch không hợp lệ | Kiểm tra thời gian và phiên giao dịch hiện tại |
| BATCH\_IN\_PROGRESS | Hệ thống đang xử lý cuối ngày | Thử lại sau khi hệ thống mở giao dịch trở lại |

### Order Processing Errors

| Code | Description | Recommended Action |
| - | - | - |
| INVALID\_ORDER\_ID | Không tìm thấy lệnh | Kiểm tra lại Order ID |
| ORDER\_STATUS\_REJECTED | Không thể thao tác với trạng thái lệnh hiện tại | Kiểm tra trạng thái lệnh trước khi thực hiện |
| ORDER\_IS\_DONE | Lệnh đã hoàn tất hoặc đã hủy | Không thể sửa hoặc hủy lệnh ở trạng thái này |
| CAN\_NOT\_CANCEL\_ATO\_ORDER | Không thể hủy lệnh ATO | Lệnh ATO không hỗ trợ hủy trong phiên hiện tại |
| CAN\_NOT\_CANCEL\_MARKET\_ORDER | Không thể hủy lệnh thị trường | Lệnh MTL/MOK/MAK không hỗ trợ hủy ngoài phiên liên tục |
| CAN\_NOT\_CANCEL\_PENDINGNEW\_ORDER\_IN\_OPEN\_SESSION | Không thể hủy lệnh đang ở trạng thái Chờ gửi | Thử lại sau khi lệnh được gửi lên sàn |
| CAN\_NOT\_CANCEL\_THAT\_ORDER\_ON\_THIS\_SESSION | Không thể hủy lệnh trong phiên hiện tại | Thực hiện hủy trong phiên phù hợp |
| CAN\_NOT\_REPLACE\_PLO\_ORDER | Không thể sửa lệnh PLO | Lệnh PLO không hỗ trợ sửa trong phiên hiện tại |
| CAN\_NOT\_REPLACE\_THAT\_ORDER\_ON\_THIS\_SESSION | Không thể sửa lệnh trong phiên hiện tại | Thực hiện sửa lệnh trong phiên liên tục |
| CAN\_NOT\_PLACE\_PLO\_ORDER\_WITHOUT\_MATCHED | Không thể đặt lệnh PLO khi không có lệnh đối ứng | Đặt PLO khi đã có lệnh khớp trong phiên |
| CANNOT\_PLACE\_OPPOSITE\_ORDER | Không thể đặt lệnh ngược chiều | Kiểm tra và xử lý lệnh chờ khớp ở chiều đối diện trước |
| CANNOT\_PLACE\_OPPOSITE\_ORDER\_IN\_THIS\_SESSION | Không thể đặt lệnh đối ứng trong phiên này | Thực hiện trong phiên liên tục |
| RESOURCE\_NOT\_FOUND | Không tìm thấy tài nguyên | Kiểm tra lại thông tin định danh được yêu cầu |

### Buying Power & Margin Errors

| Code | Description | Recommended Action |
| - | - | - |
| PURCHASING\_POWER\_NOT\_ENOUGH | Không đủ sức mua | Giảm giá trị lệnh hoặc nộp thêm tiền vào tài khoản để tăng sức mua |
| PP0\_EXCEED | Vượt sức mua | Giảm giá trị hoặc khối lượng lệnh |
| QMAX\_EXCEED | Khối lượng vượt quá sức mua/sức bán tối đa | Giảm giá đặt hoặc khối lượng đặt lệnh |
| STOCK\_NOT\_ENOUGH | Không đủ chứng khoán để bán | Kiểm tra số dư khả dụng trước khi đặt lệnh bán |
| VIOLATE\_POOL\_RULE | Vượt hạn mức Pool cho vay | Giảm khối lượng hoặc chọn gói vay khác |
| VIOLATE\_ROOM\_RULE | Vượt hạn mức Room cho vay | Giảm khối lượng hoặc chờ hạn mức được cập nhật |
| OUT\_OF\_MARGIN\_BASKET | Mã chứng khoán không thuộc danh mục ký quỹ | Kiểm tra danh mục mã được phép mua vay |

### Symbol Status Errors

| Code | Description | Recommended Action |
| - | - | - |
| SYMBOL\_NOT\_EXIST | Không tìm thấy mã chứng khoán | Kiểm tra lại mã chứng khoán |
| CAN\_NOT\_PLACE\_ORDER\_ON\_HALTED\_SYMBOL | Mã đang tạm ngừng giao dịch | Đặt lại sau khi mã được giao dịch trở lại |
| CAN\_NOT\_PLACE\_ORDER\_ON\_AOM\_HALTED\_SYMBOL | Mã bị chặn giao dịch trong phiên liên tục | Thử lại trong phiên phù hợp |
| CAN\_NOT\_PLACE\_ORDER\_ON\_SUSPENDED\_SYMBOL | Mã bị đình chỉ giao dịch | Không thể giao dịch cho đến khi mã được mở lại |
| CAN\_NOT\_PLACE\_ORDER\_ON\_UNLISTED\_SYMBOL | Mã đã hủy niêm yết | Không thể giao dịch mã này |
| CAN\_NOT\_PLACE\_ODD\_LOT\_ORDER\_ON\_SPECIAL\_SYMBOL | Không hỗ trợ lô lẻ với mã đặc biệt này | Thực hiện giao dịch theo quy định của mã |

### Authentication & Permission Errors

| Code | Description | Recommended Action |
| - | - | - |
| FORBIDDEN | Không có quyền thực hiện thao tác | Đảm bảo tài khoản có quyền thực hiện chức năng này |
| INVALID\_OTP | OTP không hợp lệ | Kiểm tra lại mã OTP hoặc lấy mã OTP mới |
| INVALID\_TRADING\_TOKEN | Trading Token không hợp lệ hoặc hết hạn | Kiểm tra hoặc xác thực lại để lấy Trading Token mới |

### System Errors

| Code | Description | Recommended Action |
| - | - | - |
| TIMEOUT | Vượt quá thời gian xử lý | Thử lại sau bằng cơ chế exponential backoff |
| SYSTEM\_ERROR | Lỗi hệ thống | Thử lại sau. Nếu lỗi tiếp tục, liên hệ bộ phận hỗ trợ |
| REMOTE\_SERVER\_ERROR | Lỗi từ hệ thống backend | Thử lại sau hoặc liên hệ hỗ trợ nếu lỗi kéo dài |
| THIRD\_PARTY\_ERROR | Lỗi từ hệ thống bên thứ ba | Thử lại sau. Nếu lỗi tiếp tục, liên hệ bộ phận hỗ trợ |

***

## Khuyến nghị xử lý mã lỗi

* Kiểm tra HTTP Status trước — `2xx` xử lý bình thường, `4xx/5xx` đọc `code` để phân loại.
* Không retry đối với lỗi xác thực (401), phân quyền (403) và dữ liệu đầu vào (400, 422) — cần khắc phục root cause trước.
* Có thể retry với backoff cho lỗi 500, 503, `TIMEOUT` — khuyến nghị exponential backoff, tối đa 3 lần.
* Với lỗi 429, kiểm tra Header response để biết hạn mức còn lại, chờ đến thời điểm chỉ định trong header `X-RateLimit-Reset` trước khi retry.
* Khi cần hỗ trợ, cung cấp đầy đủ: HTTP Status, `code`, `message`, endpoint, thời điểm xảy ra, Request ID / Trace ID nếu có.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.