Skip to main content
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:

​
Bảng HTTP status

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

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

Param không hợp lệ — sai enum, sai range, sai format. message mô tả field cụ thể.
Thiếu param bắt buộc. Ví dụ /market/financial-data/macro thiếu type hoặc country.
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)

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/**).
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.
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.
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.
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).

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

1

Kiểm tra HTTP status trước

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

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

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.