Error Envelope
Fields
| Field | Type | Required | Description |
|---|---|---|---|
error_code | string | Yes | Machine-readable error code (see list below). Matches server enum variant exactly. |
message | string/null | No | Human-readable context. May be null. |
incoming_message | object/null | No | Echo of the request that caused the error (your original message), when available. |
Note:incoming_messageuses the same tagged format as requests ({ "type": "<snake_case>", "params": { ... } }).
Error Codes
These values map 1:1 to the server enum:| Code | When it happens | Suggested Client Action |
|---|---|---|
RateLimited | You’ve exceeded the allowed message rate (weighted per message type). | Backoff and retry later. Consider batching and respecting published limits. |
InvalidJSONFormat | Message is not valid JSON or doesn’t match the expected schema. | Validate JSON and schema before sending. Include required fields and correct types/enum values. |
AlreadyAuthenticated | You attempted to authenticate again after a successful auth on the same connection. | Do not re-auth on an already authenticated socket. |
InvalidParameter | One or more parameters are out of range, missing, or invalid for the specified message. | Correct the parameter(s) and retry. |
PermissionDenied | The API key or user lacks permission for the requested action. | Check key scopes/roles; contact support if needed. |
ServerError | Unexpected internal error. | Safe to retry after a short delay; if persistent, contact support with timestamp and incoming_message. |
InvalidOrder | The order is invalid or malformed. | Check order parameters and format; correct the order and retry. |
AlreadySubscribedToLeaderboard | The user is already subscribed to a leaderboard. | Do not attempt to subscribe again; check current subscriptions first. |
KycRequired | The user needs to complete KYC verification. | Complete KYC verification before proceeding with the requested action. |
TncRequired | The user needs to agree to the latest Terms and Conditions. | Agree to the latest Terms and Conditions. |
Rate limiting notes
The server computes message weight by the message"type" (e.g., "add_order", "cancel_order") and applies limits over a sliding window. Some messages are heavier than others. If you see RateLimited, delay and reduce frequency; prefer fewer, larger requests when possible.
Examples
1) Invalid JSON
2) Already authenticated
3) Invalid parameter
4) Permission denied
5) Rate limited
6) Server error
Client Handling Patterns
Python
Python
Node
Node
Go
Go
Authentication & Errors
- trade.qfex.com requires authentication within 1 minute of connecting.
- Attempting to re-authenticate an already authenticated connection yields
AlreadyAuthenticated.
Troubleshooting Checklist
- Validate JSON (types/enums/required fields).
- Respect rate limits (reduce burstiness; batch where possible).
- Ensure your API key has the right permissions.
- Log
incoming_messagefrom error frames to quickly reproduce issues. - For persistent
ServerError, contact [email protected] with timestamp and offendingincoming_message.