HTTP 返回碼

本文檔概述了 Habittrade REST 和 WebSocket API 中使用的標準化 HTTP 響應格式，包括 HTTP 狀態碼和錯誤碼。這些代碼幫助開發人員和自動化系統正確解讀響應、調試問題並正確處理重試邏輯。

這些代碼表示客戶端發送的請求有問題。

Code	含義	說明
`400 Bad Request`	無效請求	請求語法錯誤或缺少必要參數。
`401 Unauthorized`	驗證失敗	缺少或無效的身份驗證標頭（例如簽名、API 金鑰）。
`403 Forbidden`	WAF 限制	由於 Web 應用防火牆規則或 IP 黑名單，請求被阻止。
`404 Not Found`	找不到資源	請求的端點或對象不存在。
`409 Conflict`	部分成功	取消並重下單操作中取消失敗但新訂單已接受時返回。
`418 IP Banned`	IP 封禁	由於多次 429 超限，IP 被臨時封禁。
`429 Too Many Requests`	超出請求速率限制	超過請求速率限制。`Retry-After` 標頭中包含重試延遲時間。

這些代碼表示 Habittrade 平台的 內部錯誤。不應將其視為最終失敗，應 將訂單狀態視為未知 並通過 GET /orders/{id} 或類似接口重新確認。

當 API 請求發生異常時，系統將在 HTTP 響應正文（Response Body）中返回結構化的錯誤訊息，其中包含以下關鍵字段：

範例:

json

{
  "code": 10010008,
  "message": "Signature verification failed"
}

HTTP狀態碼	錯誤碼	Message	描述
2XX	0	Successful	請求已成功處理且無任何錯誤
405	10010000	Method Not Allowed	請求使用的HTTP方法不被允許，或使用了錯誤的`ContentType`
400	10010001	Invalid argument(s)	請求中提供的一個或多個參數無效或缺失
400	10010002	The connection was not accepted because it is not a WebSocket request	因不符合WebSocket協議要求，連接請求已被拒絕
400	10010004	Authenticate failed	因未明確原因導致身分驗證失敗，請檢查憑證及`驗證`流程
401	10010005	Missing required headers	請求缺少必要的驗證標頭，請檢查`驗證`流程中的必需標頭
401	10010006	Invalid timestamp	請求中的時間戳無效或超出可接受時間範圍
401	10010007	Invalid API Key	提供的API金鑰無效或不存在
401	10010008	Signature verification failed	提供的簽名與預期不匹配，請檢查`驗證`流程是否合規
404	10010011	Resource not found	請求的資源不存在，或請求路徑有誤
500	10010012	Internal server error	伺服器處理請求時發生未預期錯誤
500	10010013	Internal server error, wrong http status	伺服器處理請求時發生異常，導致返回錯誤HTTP狀態碼
401	10010015	The client's IP address is not in the whitelist	已啟用IP白名單，當前調用IP不在白名單內
429	10010017	Too many requests	請求過於頻繁或超出配額限制

在 UAT 環境 (https://api-uat.habittrade.com) 中，某些錯誤響應可能被模擬以便測試您的客戶端錯誤處理邏輯。請參考測試部分了解如何故意觸發每種錯誤。

HTTP 返回碼 ​