Tham Chiếu Mã Lỗi & Trạng Thái

Hướng dẫn toàn diện về mã lỗi Smart Money API, mã trạng thái HTTP và các bước khắc phục sự cố. Hiểu phản hồi lỗi và giải quyết các vấn đề tích hợp nhanh chóng.

Mã Thành Công 2xx

Phản hồi thành công cho biết yêu cầu đã được xử lý thành công.

Mã	Trạng Thái	Ý Nghĩa
200	OK	Yêu cầu thành công. Phản hồi chứa dữ liệu được yêu cầu.
201	Created	Tài nguyên đã được tạo thành công. Phản hồi bao gồm tài nguyên mới.
204	No Content	Yêu cầu thành công nhưng không có nội dung để trả về (ví dụ: DELETE).

Ví dụ Phản Hồi 200

JSON

{
  "success": true,
  "data": {
    "total": 42,
    "positions": [...],
    "pagination": {
      "page": 1,
      "limit": 50
    }
  },
  "timestamp": "2026-03-21T14:35:22Z"
}

Mã Lỗi Máy Khách 4xx

Lỗi máy khách cho biết yêu cầu không hợp lệ hoặc sai cú pháp. Sửa yêu cầu và thử lại.

Mã	Trạng Thái	Nguyên Nhân
400	Bad Request	Cú pháp yêu cầu không hợp lệ. Kiểm tra tham số truy vấn, tiêu đề và nội dung yêu cầu.
401	Unauthorized	Thiếu hoặc sai thông tin xác thực. Kiểm tra API key hoặc JWT token của bạn.
402	Payment Required	Thanh toán đăng ký của bạn thất bại. Cập nhật thông tin thanh toán trong tài khoản của bạn.
403	Forbidden	Đã xác thực nhưng không được phép truy cập tài nguyên này. Gói của bạn không bao gồm tính năng này.
404	Not Found	Tài nguyên không tồn tại. Kiểm tra URL endpoint và các tham số.
429	Too Many Requests	Vượt quá giới hạn tốc độ. Đợi trước khi thử lại. Kiểm tra tiêu đề Retry-After.
422	Unprocessable Entity	Kiểm tra không thành công. Tham số yêu cầu không hợp lệ hoặc thiếu các trường bắt buộc.

Ví Dụ Lỗi Xác Thực

Thiếu API Key (401)

JSON

{
  "success": false,
  "error": {
    "code": "AUTH_MISSING_KEY",
    "message": "Authentication credentials not provided.",
    "resolution": "Include your API key in the Authorization header: Authorization: Bearer sk_live_..."
  },
  "timestamp": "2026-03-21T14:35:22Z"
}

API Key Không Hợp Lệ (401)

JSON

{
  "success": false,
  "error": {
    "code": "AUTH_INVALID_KEY",
    "message": "Invalid or expired API key.",
    "resolution": "Generate a new API key from your console at https://smartmoneyapi.com/console"
  },
  "timestamp": "2026-03-21T14:35:22Z"
}

Giới Hạn Tốc Độ (429)

Khi bạn vượt quá hạn ngạch API, máy chủ sẽ trả về 429 Too Many Requests. Kiểm tra các tiêu đề phản hồi để biết thông tin giới hạn tốc độ:

Tiêu Đề HTTP

X-Requests-Remaining: 0
X-Requests-Limit: 200
X-Requests-Reset: 1711116922
Retry-After: 3600

Phản Hồi Lỗi Giới Hạn Tốc Độ

JSON

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Daily API request limit (200) exceeded.",
    "resolution": "Upgrade to Trader ($29/month, 1,000 requests/day) or Pro ($79/month, 5,000 requests/day) plan.",
    "reset_at": "2026-03-22T09:00:00Z"
  },
  "timestamp": "2026-03-21T14:35:22Z"
}

Lỗi Kiểm Tra (422)

Lỗi kiểm tra xảy ra khi các tham số yêu cầu của bạn không hợp lệ hoặc thiếu các trường bắt buộc.

JSON

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed.",
    "details": [
      {
        "field": "symbol",
        "error": "Invalid trading pair. Expected format: BTCUSDT"
      },
      {
        "field": "min_position_size",
        "error": "Must be a positive number"
      }
    ],
    "resolution": "Fix the validation errors and retry."
  },
  "timestamp": "2026-03-21T14:35:22Z"
}

Mã Lỗi Máy Chủ 5xx

Lỗi máy chủ cho biết có vấn đề từ phía chúng tôi. Những lỗi này là tạm thời và thường được giải quyết nhanh chóng. Triển khai logic thử lại với độ trễ tăng dần.

Mã	Trạng Thái	Hành Động
500	Internal Error	Lỗi máy chủ không mong muốn. Thử lại với độ trễ tăng dần.
502	Bad Gateway	Gián đoạn dịch vụ tạm thời. Thử lại sau vài giây.
503	Service Unavailable	Bảo trì hoặc gián đoạn tạm thời. Kiểm tra trang trạng thái. Thử lại sau khoảng thời gian Retry-After.
504	Gateway Timeout	Yêu cầu mất quá nhiều thời gian. Máy chủ có thể đã xử lý nó. Kiểm tra tính idempotent.

Ví Dụ Lỗi Máy Chủ (503)

JSON

{
  "success": false,
  "error": {
    "code": "SERVICE_UNAVAILABLE",
    "message": "Service temporarily unavailable due to maintenance.",
    "resolution": "Please retry after 5 minutes. Track status at https://status.smartmoneyapi.com"
  },
  "timestamp": "2026-03-21T14:35:22Z"
}

Hướng Dẫn Khắc Phục Sự Cố

401 Unauthorized - API Key Không Hợp Lệ

Vấn Đề: Nhận được lỗi 401 ngay cả khi có API key.

Giải Pháp:

Xác minh API key được bao gồm trong tiêu đề Authorization với tiền tố "Bearer"
Kiểm tra xem API key của bạn có hết hạn hoặc bị thu hồi không
Đảm bảo bạn đang sử dụng đúng key (production, staging, hoặc development)
Tạo một API key mới từ console của bạn nếu key hiện tại bị mất

403 Forbidden - Tính Năng Không Khả Dụng

Vấn Đề: Nhận được lỗi 403 trên một số endpoint.

Giải Pháp:

Kiểm tra cấp độ API của bạn. Một số endpoint yêu cầu gói Trader hoặc Pro
Nâng cấp gói của bạn tại /pricing.html để truy cập các tính năng cao cấp
Xác minh API key có các phạm vi cần thiết được kích hoạt
Liên hệ hỗ trợ nếu bạn tin rằng bạn nên có quyền truy cập

429 Too Many Requests - Bị Giới Hạn Tốc Độ

Vấn Đề: Nhận được lỗi 429 và bị giới hạn tốc độ.

Giải Pháp:

Triển khai logic thử lại với độ trễ tăng dần (đợi 1s, 2s, 4s, v.v.)
Lưu trữ phản hồi để tránh các cuộc gọi API dư thừa
Sử dụng WebSocket để nhận dữ liệu thời gian thực thay vì polling các endpoint REST
Nâng cấp gói của bạn để có hạn ngạch cao hơn (Trader 1,000/ngày, Pro 5,000/ngày)
Gộp nhiều truy vấn vào một yêu cầu duy nhất khi có thể

400 Bad Request - Tham Số Không Hợp Lệ

Vấn Đề: Nhận được lỗi 400 với các yêu cầu không hợp lệ.

Giải Pháp:

Kiểm tra tài liệu API để biết các tham số bắt buộc và tùy chọn
Xác minh loại tham số (chuỗi vs số, mảng vs đối tượng)
Đảm bảo JSON hợp lệ và được định dạng đúng
Sử dụng URL endpoint chính xác với các tham số đường dẫn phù hợp
Kiểm tra lỗi chính tả trong tên tham số truy vấn

Lỗi máy chủ 5xx - Gián đoạn tạm thời

Vấn đề: Nhận lỗi 500, 502, 503 hoặc 504.

Giải pháp:

Kiểm tra trạng thái dịch vụ tại https://status.smartmoneyapi.com
Triển khai cơ chế thử lại tự động với backoff theo cấp số nhân (tối đa 5-10 lần thử)
Chờ 30-60 giây trước khi thử lại với lỗi 503
Sử dụng tiêu đề Retry-After để xác định thời gian thử lại
Đăng ký trang trạng thái để nhận thông báo sự cố

Định dạng phản hồi lỗi

Tất cả phản hồi lỗi đều tuân theo định dạng thống nhất:

JSON

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Thông báo lỗi dễ hiểu",
    "details": {...},
    "resolution": "Các bước khắc phục sự cố"
  },
  "timestamp": "2026-03-21T14:35:22Z"
}

Cần thêm trợ giúp?

Kiểm tra tài liệu API của chúng tôi hoặc liên hệ hỗ trợ với mã lỗi và chi tiết yêu cầu của bạn.

Tài liệu tham khảo API

Nhận hỗ trợ

Có thắc mắc? Kiểm tra tài liệu của chúng tôi hoặc liên hệ với bộ phận hỗ trợ.

Mở Console