錯誤代碼與狀態參考
Smart Money API 錯誤代碼、HTTP 狀態碼及疑難排解步驟的完整指南。快速理解錯誤回應並解決整合問題。
2xx 成功代碼
成功回應表示請求已成功處理。
| 代碼 | 狀態 | 含義 |
|---|---|---|
| 200 | OK | 請求成功。回應主體包含請求的資料。 |
| 201 | Created | 資源創建成功。回應包含新資源。 |
| 204 | No Content | 請求成功但無內容返回（例如 DELETE 操作）。 |
200 回應範例
JSON
{
"success": true,
"data": {
"total": 42,
"positions": [...],
"pagination": {
"page": 1,
"limit": 50
}
},
"timestamp": "2026-03-21T14:35:22Z"
}
4xx 客戶端錯誤代碼
客戶端錯誤表示請求格式錯誤或無效。修正請求後重試。
| 代碼 | 狀態 | 原因 |
|---|---|---|
| 400 | Bad Request | 請求語法錯誤。檢查查詢參數、標頭及請求主體。 |
| 401 | Unauthorized | 缺少或無效的驗證憑證。檢查您的 API 金鑰或 JWT 令牌。 |
| 402 | Payment Required | 訂閱付款失敗。請更新帳戶中的帳單資訊。 |
| 403 | Forbidden | 已驗證但無權訪問此資源。您的方案未包含此功能。 |
| 404 | Not Found | 資源不存在。檢查端點 URL 及參數。 |
| 429 | Too Many Requests | 超過速率限制。請等待後重試。檢查 Retry-After 標頭。 |
| 422 | Unprocessable Entity | 驗證失敗。請求參數無效或缺少必填欄位。 |
驗證錯誤範例
缺少 API 金鑰 (401)
JSON
{
"success": false,
"error": {
"code": "AUTH_MISSING_KEY",
"message": "未提供驗證憑證。",
"resolution": "在 Authorization 標頭中包含您的 API 金鑰：Authorization: Bearer sk_live_..."
},
"timestamp": "2026-03-21T14:35:22Z"
}
無效 API 金鑰 (401)
JSON
{
"success": false,
"error": {
"code": "AUTH_INVALID_KEY",
"message": "無效或過期的 API 金鑰。",
"resolution": "從您的控制台生成新 API 金鑰：https://smartmoneyapi.com/console"
},
"timestamp": "2026-03-21T14:35:22Z"
}
速率限制 (429)
當超過 API 配額時，伺服器會返回 429 Too Many Requests。檢查回應標頭中的速率限制資訊：
HTTP 標頭
X-Requests-Remaining: 0
X-Requests-Limit: 200
X-Requests-Reset: 1711116922
Retry-After: 3600
速率限制錯誤回應
JSON
{
"success": false,
"error": {
"code": "RATE_LIMIT_EXCEEDED",
"message": "每日 API 請求限制 (10) 已超過。",
"resolution": "升級至 Trader ($29/月, 400 次請求/日) 或 Pro ($79/月, 4,000 次請求/日) 方案。",
"reset_at": "2026-03-22T09:00:00Z"
},
"timestamp": "2026-03-21T14:35:22Z"
}
驗證錯誤 (422)
驗證錯誤發生於請求參數無效或缺少必填欄位時。
JSON
{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "請求驗證失敗。",
"details": [
{
"field": "symbol",
"error": "無效交易對。預期格式：BTCUSDT"
},
{
"field": "min_position_size",
"error": "必須為正數"
}
],
"resolution": "修正驗證錯誤後重試。"
},
"timestamp": "2026-03-21T14:35:22Z"
}
5xx 伺服器錯誤代碼
伺服器錯誤表示我方出現問題。這些是暫時性的，通常會快速解決。請實作指數退避重試邏輯。
| 代碼 | 狀態 | 操作 |
|---|---|---|
| 500 | Internal Error | 意外的伺服器錯誤。使用指數退避重試。 |
| 502 | Bad Gateway | 暫時性服務中斷。幾秒後重試。 |
| 503 | Service Unavailable | 維護或暫時性停機。檢查狀態頁面。在 Retry-After 間隔後重試。 |
| 504 | Gateway Timeout | 請求耗時過長。伺服器可能已處理該請求。檢查冪等性。 |
伺服器錯誤範例 (503)
JSON
{
"success": false,
"error": {
"code": "SERVICE_UNAVAILABLE",
"message": "因維護暫時無法提供服務。",
"resolution": "請 5 分鐘後重試。追蹤狀態：https://status.smartmoneyapi.com"
},
"timestamp": "2026-03-21T14:35:22Z"
}
疑難排解指南
401 Unauthorized - 無效 API 金鑰
問題： 即使有 API 金鑰仍收到 401 錯誤。
解決方案：
- 確認 API 金鑰已包含在 Authorization 標頭中並帶有 "Bearer" 前綴
- 檢查您的 API 金鑰是否未過期或已被撤銷
- 確保您使用的是正確的金鑰（生產、預發佈或開發環境）
- 若當前金鑰遺失，請從控制台生成新 API 金鑰
403 Forbidden - 功能不可用
問題： 在某些端點上收到 403 錯誤。
解決方案：
- 檢查您的 API 層級。部分端點需要 Trader 或 Pro 方案
- 升級您的方案至 /pricing.html 以訪問高級功能
- 確認 API 金鑰已啟用所需範圍
- 若您認為應有訪問權限，請聯繫支援
429 Too Many Requests - 速率限制
問題： 收到 429 錯誤並被限制速率。
解決方案：
- 實作指數退避重試邏輯（等待 1 秒、2 秒、4 秒等）
- 快取回應以避免冗餘 API 呼叫
- 使用 WebSocket 獲取即時數據而非輪詢 REST 端點
- 升級方案以獲得更高配額（Trader 1,000/日，Pro 5,000/日）
- 盡可能將多個查詢批次處理為單一請求
400 Bad Request - 無效參數
問題： 收到格式錯誤請求的 400 錯誤。
解決方案：
- 檢查 API 文件中的必填和選填參數
- 驗證參數類型（字串 vs 數字，陣列 vs 物件）
- 確保 JSON 有效且格式正確
- 使用正確的端點 URL 及適當的路徑參數
- 檢查查詢參數名稱中的拼寫錯誤
5xx 伺服器錯誤 - 暫時性中斷
問題： 遇到 500、502、503 或 504 錯誤。
解決方案：
- 檢查服務狀態：https://status.smartmoneyapi.com
- 實施帶有指數退避的自動重試（最多 5-10 次嘗試）
- 在重試 503 錯誤前等待 30-60 秒
- 使用 Retry-After 標頭來確定重試時間
- 訂閱狀態頁面以獲取事件通知
錯誤回應格式
所有錯誤回應都遵循一致的格式：
JSON
{
"success": false,
"error": {
"code": "ERROR_CODE",
"message": "人類可讀的錯誤訊息",
"details": {...},
"resolution": "解決問題的步驟"
},
"timestamp": "2026-03-21T14:35:22Z"
}