Error Codes

WebSocket quote push involves two types of error codes from different layers:

• Channel error codes: Returned by the WebSocket channel layer, occurring during authentication or low-level request processing. Values are integers in the 4xxx / 5xxx range.
• Subscription response codes: Returned by the business layer, appearing only in responses to subscribe and unsubscribe requests. Values are small integers from 0–5.

The two types of error codes are independent of each other, with non-overlapping value ranges that can be distinguished directly by numeric range.

---

Channel Error Codes

Channel errors occur before a request reaches business logic, returned by the WebSocket gateway or authentication service.

Response Format

{
  "id": "req-001",
  "code": 4002,
  "msg": "auth_failed"
}

Note: The field name is msg, which differs from the message field in subscription responses.

Error Code Description

code	Meaning	Common Cause	Recommended Action
4000	Request format error	The frame structure does not conform to the protocol, e.g. malformed JSON or empty action field.	Check the request frame format and resend after fixing.
4001	Not yet authenticated	A business request was sent before authentication completed.	Complete Auth first; send business requests only after receiving session_id.
4002	Authentication failed	credential_id does not exist, signature verification failed, or Bearer Token is expired or invalid.	Check credentials and signature logic; for OAuth2, refresh the Token before re-establishing the connection.
4003	Insufficient permissions	The credential's authorization scope does not include the requested interface permission.	Confirm whether the credential has been authorized for this interface; if using OAuth2, check the scope requested during authorization.
4004	Interface does not exist	action is incorrect, or an interface not exposed by the server was requested.	Review the interface documentation and verify the action name spelling.
5000	Internal server error	An unexpected exception occurred while the server was processing the request.	Contact server support for investigation; automatic retry is not recommended.
5002	Gateway error	A network exception on the server side prevented the request from reaching the backend.	Retry after a short wait; if it persists, check your network environment or contact server support.
5003	Service temporarily unavailable	Server load is too high to process new requests temporarily.	Wait a moment and retry; a backoff strategy is recommended.
5004	Request timeout	The server timed out and was unable to return a result within the specified time.	Retry after a short wait; if timeouts persist, contact server support for investigation.

---

Subscription Response Codes

Subscription response codes appear only in responses to subscribe (subscribe) and unsubscribe (unsubscribe) requests, returned after business-layer processing.

Response Format

{
  "id": "sub-001",
  "code": 0,
  "message": "success"
}

Note: The field name is message, which differs from the msg field in channel errors.

Success example:

{
  "id": "sub-001",
  "code": 0,
  "message": "success"
}

Error example:

{
  "id": "sub-002",
  "code": 4,
  "message": "sub quota exceeded, max=100"
}

Error Code Description

code	Meaning	Common Cause	Recommended Action
0	Success	The subscribe, unsubscribe, or session cleanup request was processed successfully.	Continue receiving pushes, or update local subscription state.
1	Required session information missing	Subscription was initiated before completing auth; the connection session is abnormal; the gateway could not establish a valid user session.	Re-establish the WebSocket connection, complete login/auth first, then re-subscribe.
2	Unsupported action type	action is incorrect, or an action not supported by the server was used.	Check that action is subscribe or unsubscribe.
3	System exception	A dependency used by the server for subscription quota checks is temporarily unavailable.	Retry after a short backoff; if it persists, contact technical support with the request ID, time, and returned content.
4	Subscription quota insufficient	The current account's subscription count exceeds the upper limit.	Reduce subscribed symbols or data types; unsubscribe symbols no longer in use; confirm the account's quote permissions and quota.
5	Invalid K-line period parameter	kline.period is out of the supported range, or the period format is incorrect.	Re-pass the parameter using a K-line period supported in Subscribe and Unsubscribe.

TIP

On receiving a non-0 response, do not treat the request as having taken effect. The client should keep its local subscription state consistent with the server response: only mark as subscribed after a subscription succeeds, and only remove the local subscription record after an unsubscribe succeeds.

Retry Recommendations

Error Type	Retry Immediately?	Recommended Strategy
Temporary system error (code=3)	Yes	Retry after a short wait; avoid high-frequency requests.
Parameter error (code=2, code=5)	No	Correct the parameters before retrying.
Quota exceeded (code=4)	No	Reduce the subscription count or increase quota first, then retry.
Missing session (code=1)	No	Reconnect and complete auth before subscribing.