Error codes - FHSC - Open API docs

API trả về lỗi dưới 2 dạng:

HTTP status ở response header (4xx / 5xx).
error_code ở response body — string "0" khi thành công, mã khác "0" khi lỗi.

Body response lỗi có shape:

{
  "error_code": "AUTH_SIGNATURE_INVALID",
  "message": "Invalid signature"
}

Bảng HTTP status

Status	Ý nghĩa	Khi nào
`200`	OK	Request thành công, `error_code: "0"`
`400`	Bad Request	Thiếu / sai param, body không hợp lệ
`401`	Unauthorized	API key sai, signature không hợp lệ, timestamp lệch, nonce reused
`403`	Forbidden	IP bị chặn, scope bị từ chối, hoặc 2FA session (`X-FH-2FA-TOKEN`) hết hạn / không hợp lệ
`429`	Too Many Requests	Vượt rate limit — xem Rate limits
`500`	Internal Server Error	Lỗi server. Retry sau khi backoff

Mã lỗi xác thực (HTTP 401)

AUTH_API_KEY_INVALID

API key không hợp lệ hoặc đã bị thu hồi. Liên hệ team Finhay để kiểm tra trạng thái key hoặc cấp key mới.

AUTH_SIGNATURE_INVALID

X-FH-SIGNATURE không match với payload do client tính. Nguyên nhân phổ biến:

Sai thuật toán: phải là HMAC-SHA256 với output hex lowercase.
Sai thứ tự / format payload: đúng phải là {TIMESTAMP}\n{METHOD}\n{PATH}[?{QUERY}]\n{BODYHASH}.
BODYHASH thiếu hoặc tính sai khi request có body.
QUERY không canonical (sort key sai, encode sai).

Xem chi tiết ở Authentication — Signing payload.

AUTH_TIMESTAMP_OUT_OF_RANGE

X-FH-TIMESTAMP lệch quá ±30 giây so với giờ server. Đảm bảo client đồng bộ NTP. X-FH-TIMESTAMP là Unix timestamp tính bằng mili-giây, không phải giây.

AUTH_NONCE_REUSED

X-FH-NONCE đã được sử dụng với cùng apiKey trong vòng 5 phút gần nhất. Mỗi request phải sinh nonce mới — khuyến nghị dùng UUIDv4.

AUTH_BODYHASH_MISMATCH

X-FH-BODYHASH không match với SHA256(body) server tính. Đảm bảo:

Body được serialize stable (cùng JSON string client ký và client gửi).
Hash là hex lowercase, không phải base64.

Mã lỗi request (HTTP 400)

INVALID_PARAMETER

Param không hợp lệ — sai enum, sai range, sai format. message mô tả field cụ thể.

MISSING_REQUIRED_PARAMETER

Thiếu param bắt buộc. Ví dụ /market/financial-data/macro thiếu type hoặc country.

MUTUALLY_EXCLUSIVE_PARAMETER

Truyền cùng lúc nhiều param loại trừ lẫn nhau. Ví dụ /market/stock-realtime chỉ được truyền đúng 1 trong symbol / symbols / exchange.

Mã lỗi rate limit (HTTP 429)

RATE_LIMIT_EXCEEDED

Vượt giới hạn request trong cửa sổ thời gian hiện tại. Response kèm header X-RateLimit-Reset cho biết thời điểm có thể retry.Xem chi tiết ở Rate limits.

Mã lỗi 2FA session (HTTP 403)

Áp dụng cho các endpoint nhóm Thực thi lệnh (preview — POST / PUT / DELETE dưới /trading/oa/**).

OTP_SESSION_REQUIRED

Chưa có 2FA session — client chưa gửi header X-FH-2FA-TOKEN. Khởi tạo OTP flow để xin token mới.

OTP_SESSION_EXPIRED

Token đã hết hạn (token có tuổi thọ 1 ngày giao dịch). Chạy lại OTP flow để xin token mới rồi retry.

OTP_SESSION_INVALID

Token không hợp lệ — chữ ký sai hoặc bị làm giả. Không retry, xác minh lại logic lưu trữ / truyền token ở client.

OTP_SESSION_REVOKED

Token đã bị thu hồi (user logout, đổi API key, hoặc admin force revoke). Chạy lại OTP flow để xin token mới.

Order-level error codes (Thực thi lệnh — preview)

Semantic đặc biệt: với 3 endpoint nhóm Thực thi lệnh, HTTP 200 không đồng nghĩa với lệnh đã được sàn chấp nhận. Phải đọc result[].code trong body — nếu non-null thì sàn từ chối lệnh (result[].order_status thường là REJECTED / FAILED, result[].rejected_reason chứa lý do).

`code`	Ý nghĩa
`-400116`, `QMAX_EXCEED`	Vượt quá sức mua / sức bán.
`-900017`, `-10011`, `INVALID_PRICE_LOT`	Giá / lot không hợp lệ — kiểm tra bước nhảy giá và lot size theo sàn.
`-700106`, `-700104`, `-700105`	Điều chỉnh số lượng / giá đặt rồi thử lại.
`-700114`	Đối với lô lẻ, chỉ được đặt lệnh `LO`.
`-300025`	Ngoài giờ giao dịch — vui lòng đặt lại trong phiên sau.
`-100113`, `INVALID_ORDER_TYPE_FOR_THIS_SESSION`	Loại lệnh không phù hợp với phiên hiện tại (ví dụ đặt `ATO` ngoài phiên mở cửa).
`-400099`	Chứng khoán nằm ngoài danh mục được phép mua.
`-700069`, `CAN_NOT_PLACE_ORDER_ON_HALTED_SYMBOL`	Mã chứng khoán đang bị hạn chế / tạm dừng giao dịch.
`MUST_PUBLISH_TRADE_INFO`	Yêu cầu công bố thông tin trước khi giao dịch (cổ đông lớn / nội bộ).
`-701111`	(Modify) Lệnh đã khớp một phần — chỉ sửa được phần chưa khớp.
`FAILED`	Có lỗi xảy ra phía sàn / ORS, vui lòng thử lại.

Chiến lược xử lý lỗi

Kiểm tra HTTP status trước

2xx → parse body. 4xx / 5xx → đọc error_code để phân loại.

Retry chỉ khi đúng case

Retry với backoff cho 429 (tới X-RateLimit-Reset) và 5xx (exponential backoff, max 3 lần).
Không retry cho 400 và 401 — fix root cause trước.

Ghi log đủ context

Khi có lỗi, ghi log đầy đủ: error_code, message, traceId (nếu có trong response thành công trước đó), HTTP status, request path. Khi báo team hỗ trợ, cung cấp các trường này.

​Bảng HTTP status

​Mã lỗi xác thực (HTTP 401)

​Mã lỗi request (HTTP 400)

​Mã lỗi rate limit (HTTP 429)

​Mã lỗi 2FA session (HTTP 403)

​Order-level error codes (Thực thi lệnh — preview)

​Chiến lược xử lý lỗi

Bảng HTTP status

Mã lỗi xác thực (HTTP 401)

Mã lỗi request (HTTP 400)

Mã lỗi rate limit (HTTP 429)

Mã lỗi 2FA session (HTTP 403)

Order-level error codes (Thực thi lệnh — preview)

Chiến lược xử lý lỗi