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

# Danh sách Mã lỗi hệ thống

> Danh mục mã lỗi HTTP, mã lỗi hệ thống và nguyên nhân chi tiết trên SSI FastConnect API.

## Overview

Trang này định nghĩa danh sách các **Mã lỗi hệ thống (System Error Codes)** và **Mã trạng thái HTTP (HTTP Status Codes)** tiêu chuẩn mà hệ thống **SSI FastConnect API** trả về. Phản hồi lỗi giúp phân biệt giữa lỗi hệ thống (Gateway, Network, Server) và lỗi nghiệp vụ (Business Validation / FCO).

***

## Mã Trạng Thái HTTP (HTTP Status Codes)

| HTTP Code | Trạng Thái | Mô Tả Nguyên Nhân |
| :-: | :- | :- |
| `200` | **OK** | Request xử lý thành công. |
| `400` | **Bad Request** | Tham số truyền vào không hợp lệ, thiếu trường bắt buộc hoặc sai định dạng payload. |
| `401` | **Unauthorized** | Header thiếu Token, Access Token không hợp lệ hoặc đã hết hạn. |
| `403` | **Forbidden** | Token không có quyền truy cập tài nguyên (ví dụ: dùng Market Data Token để gọi API Trading). |
| `404` | **Not Found** | Endpoint hoặc đường dẫn URL không tồn tại trên Gateway. |
| `429` | **Too Many Requests** | Vượt quá giới hạn tần suất gọi API (Rate Limit / Quota Exceeded). |
| `500` | **Internal Server Error** | Lỗi xử lý nội bộ phía máy chủ SSI. |
| `502` | **Bad Gateway** | Gateway gặp sự cố khi kết nối tới Core Trading / Core Data. |
| `503` | **Service Unavailable** | Hệ thống đang bảo trì định kỳ hoặc đang trong quá trình nâng cấp. |
| `504` | **Gateway Timeout** | Yêu cầu bị phản hồi chậm hoặc timeout từ phía Core System. |

***

## Bảng Chi Tiết Mã Lỗi Hệ Thống (System Error Codes)

<ResponseField name="SYS_001" type="string">
  **Invalid Signature / Authentication Failed**: Chữ ký hmac/hash hoặc thông tin xác thực không chính xác.
</ResponseField>

<ResponseField name="SYS_002" type="string">
  **Access Denied / IP Not Allowed**: IP kết nối không nằm trong danh sách IP được cấp phép (nếu có cấu hình White-list IP).
</ResponseField>

<ResponseField name="SYS_003" type="string">
  **Session Expired**: Phiên làm việc đã hết hạn. Yêu cầu đăng nhập hoặc Refresh Token lại.
</ResponseField>

<ResponseField name="SYS_004" type="string">
  **Rate Limit Exceeded**: Vượt số lượng request tối đa cho phép trên giây/phút (\$RPS/RPM\$).
</ResponseField>

<ResponseField name="SYS_005" type="string">
  **Maintainance Mode**: Hệ thống đang tạm ngừng để bảo trì ngoài giờ giao dịch.
</ResponseField>

<ResponseField name="SYS_099" type="string">
  **Unknown System Error**: Lỗi hệ thống chưa xác định.
</ResponseField>

***

## Cấu Trúc Response Lỗi Hệ Thống Mẫu

```json theme={null}
{
  "code": "SYS_004",
  "message": "Rate limit exceeded. Please slow down your requests.",
  "status": 429,
  "timestamp": "2026-08-18T15:05:00Z"
}
```

***

## Hướng Dẫn Xử Lý Chi Tiết (Troubleshooting)

<AccordionGroup>
  <Accordion title="Lỗi 401 / 403 (Authentication & Permission)" icon="key">
    * Kiểm tra xem Header đã bao gồm `Authorization: Bearer <AccessToken>` chưa.
    * Đảm bảo bạn đã gọi API cấp **OTP** nếu thực hiện các endpoint thuộc nhóm **Trading**.
  </Accordion>

  <Accordion title="Lỗi 429 (Rate Limit)" icon="gauge">
    * Giảm tần suất gửi HTTP Requests. - Đọc các thông số trả về trên Response Header: - `X-RATELIMIT-LIMIT`: Giới hạn tối đa. - `X-RATELIMIT-REMAINING`: Số lượng request còn lại. - `X-RATELIMIT-RESET`: Thời gian (Unix timestamp) reset quota.
  </Accordion>

  <Accordion title="Lỗi 503 / 504 (Bảo trì / Timeout)" icon="server">
    * Kiểm tra lại lịch bảo trì hệ thống của SSI.
    * Xây dựng cơ chế **Retry** tự động với khoảng thời gian trễ tăng dần (Exponential Backoff).
  </Accordion>
</AccordionGroup>


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