HTTP Return Codes

This document outlines the standardized HTTP response format, including HTTP status codes and error codes, used across the Habittrade REST and WebSocket API. These codes help developers and automated systems properly interpret responses, debug issues, and handle retry logic appropriately.

---

✅ 2XX Success

Code	Meaning	Description
200 OK	Success	Request was processed successfully.
201 Created	Resource Created	Used for POST operations where a new object is created (e.g., an order).
204 No Content	Success, No Body	Successful request, but no content is returned (e.g., successful DELETE).

⚠️ 4XX Client Errors (Your Side)

These codes indicate a problem with the request sent by the client.

Code	Meaning	Description
400 Bad Request	Invalid Request	Malformed request syntax or missing parameters.
401 Unauthorized	Auth Failure	Missing or invalid authentication headers (e.g., signature, API key).
403 Forbidden	WAF Limit Violation	Request blocked due to Web Application Firewall rules or IP blacklisting.
404 Not Found	Resource Not Found	The requested endpoint or object does not exist.
409 Conflict	Partial Success	Returned during cancelReplace: cancel fails but new order is accepted.
418 IP Banned	Banned	IP is temporarily auto-banned due to repeated 429 rate limit violations.
429 Too Many Requests	Rate Limit Exceeded	Request rate exceeded. Includes retry delay in Retry-After header.

🧱 5XX Server Errors (Habittrade Side)

These codes indicate an internal error on the Habittrade platform. They should not be treated as final failures. You should treat the order state as unknown and recheck via GET /orders/{id} or equivalent.

Code	Meaning	Description
500 Internal Server Error	Server Fault	General error on the backend. Retry or confirm order state manually.
502 Bad Gateway	Upstream Error	Our backend or matching engine may be temporarily unavailable.
503 Service Unavailable	Downtime	Server is under heavy load or in maintenance mode. Retry with backoff.
504 Gateway Timeout	Timeout	The server did not receive a timely response from an upstream component.

🚧 Retry & Fallback Best Practices

Scenario	Recommendation
429 or 418	Back off exponentially. Respect Retry-After header.
5XX	Retry after 1-3 seconds. Use GET /orders/{id} to confirm state.
409	Treat as partial success. You must check both order IDs.
Frequent 403	Check if your IP is blocked by WAF. Contact support.

🚨 Error Codes

When an API request fails, the system returns a structured error message in the HTTP response body, which contains the following key fields:

• code: Error code, please see the table below
• message: Short error description message

Example:

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

Http Status	Error code	Message	Description
2XX	0	Successful	The request was processed successfully without any errors.
405	10010000	Method Not Allowed	The HTTP method used in the request is not allowed, or used wrong ContentType
400	10010001	Invalid argument(s)	One or more arguments provided in the request are invalid or missing.
400	10010002	The connection was not accepted because it is not a WebSocket request	The connection attempt was rejected because it did not adhere to the WebSocket protocol requirements.
400	10010004	Authenticate failed	Authentication failed for an unspecified reason. Please check your credentials and Authentication process.
401	10010005	Missing required headers	Required authentication headers are missing from the request. Please check the necessary request headers in the Authentication process
401	10010006	Invalid timestamp	The timestamp provided in the request is invalid or falls outside the acceptable time range.
401	10010007	Invalid API Key	The API key provided is invalid or does not exist.
401	10010008	Signature verification failed	The signature provided does not match the expected signature for the request. Please check the Authentication process to ensure that each step complies with the rules.
404	10010011	Resource not found	TThe requested resource does not exist, or the request path is incorrect.
500	10010012	Internal server error	An unexpected error occurred on the server while processing the request.
500	10010013	Internal server error, wrong http status	An unexpected error occurred while processing the request on the server, resulting in an abnormal HTTP status being returned.
401	10010015	The client's IP address is not in the whitelist	The IP whitelist has been enabled, and the IP address currently being called is not in the whitelist.
429	10010017	Too many requests	Requests are too frequent or exceed the allocated entitlement quota.

🧪 Testing in UAT

In the UAT environment (https://api-uat.habittrade.com), certain error responses may be simulated for stress-testing your client error-handling logic. Refer to the testing section for details on how to trigger each error intentionally.