Skip to main content

Documentation Index

Fetch the complete documentation index at: https://developers.fhsc.com.vn/llms.txt

Use this file to discover all available pages before exploring further.

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ĩaKhi nào
200OKRequest thành công, error_code: "0"
400Bad RequestThiếu / sai param, body không hợp lệ
401UnauthorizedAPI key sai, signature không hợp lệ, timestamp lệch, nonce reused
429Too Many RequestsVượt rate limit — xem Rate limits
500Internal Server ErrorLỗi server. Retry sau khi backoff

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

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