API Reference

API V4 - Updated Error Codes

API V4 Error Response & Error Code Summary

Error Response Format

All error responses follow a unified format:

`{
  "error": `{
    "name": "<ERROR_CODE>",
    "message": "<error description>"
  }`
}`

1. Common Errors

The following errors are shared across all authenticated endpoints.

1.1 Authentication Errors (APISecurityMiddleware)

Error ScenarioHTTP Statuserror.nameerror.message
Missing api-key header401API_HEADER_MISSINGmissing header api-key
Missing signature header401API_HEADER_MISSINGmissing header signature
Missing site-enum header400API_HEADER_MISSINGmissing header site-enum
Missing tonce header401API_HEADER_MISSINGmissing header tonce
Tonce timestamp expired or invalid401API_REQUEST_EXPIREDAPI request expired
HMAC signature verification failed401INVALID_API_SIGNATUREinvalid API signature
API Key lacks order placement permission (PLACE_ORDER role)403ACCESS_DENIEDaccess denied
Endpoint not found (unregistered route)404NOT_FOUNDNot found
auth-service returned 401401AUTH_SERVICE_UNABLE_TO_AUTHunable to auth with auth service
auth-service returned 403403AUTH_SERVICE_ACCESS_DENIEDauth service access denied
auth-service returned 404400AUTH_SERVICE_NOT_FOUNDauth service not found
auth-service returned other errors500AUTH_SERVICE_INTERNAL_SERVER_ERRORauth service internal server error

1.2 Rate Limiting Errors

Error ScenarioHTTP Statuserror.nameerror.message
Trading endpoints rate exceeded (POST/DELETE /order)429EXCEEDED_RATE_LIMITrate limit exceeded
Query endpoints rate exceeded (GET /order, /execution, /user/wallet)429EXCEEDED_RATE_LIMITrate limit exceeded

1.3 Global Error Handler

Error ScenarioHTTP Statuserror.nameerror.message
Uncaught non-HttpException error500INTERNAL_SERVER_ERRORinternal server error

1.4 User Context Resolution Errors

Error ScenarioHTTP Statuserror.nameerror.message
Missing user info (no apiKey or unable to resolve userId)400REQUEST_MISSING_USER_INFOrequest is missing information needed to identify the userBusiness Logic

2. Order Endpoints

2.1 POST /api/v4/order — Place Order

Error ScenarioHTTP Statuserror.nameerror.message
Missing symbol parameter400INVALID_SYMBOLinvalid symbol
Missing side parameter400INVALID_SIDEinvalid order side
Missing ordType parameter400INVALID_TYPEinvalid order type
Missing orderQty parameter400REQUIRED_QTYorder quantity is required
Missing price for Limit order400REQUIRED_PRICEorder price is required
Incompatible ordType and timeInForce400INVALID_ORDER_TYPE_AND_TIME_IN_FORCEorder type {ordType} and time in force {timeInForce} don't work together
Incompatible ordType and execInst400INVALID_ORDER_TYPE_AND_EXEC_INSTorder type {ordType} and exec inst {execInst} don't work together
Invalid currency pair (MG engine)400INVALID_CURRENCYorder invalid currency
Invalid price (MG engine)400INVALID_PRICEorder invalid price
Invalid price step400INVALID_PRICE_STEPorder invalid price step
Invalid quantity400INVALID_QTYorder invalid quantity
Invalid quantity step400INVALID_QTY_STEPorder invalid quantity step
Insufficient balance (cash)400INSUFFICIENT_HOLDINGSorder insufficient holdings
Insufficient balance (holdings)400INSUFFICIENT_HOLDINGSorder insufficient holdings
No holdings400NO_HOLDINGSorder no holdings
No liquidity (IOC order)400NO_LIQUIDITYorder no liquidity
Negative price400PRICE_NEGATIVEorder price negative
Price too high400PRICE_TOO_HIGHorder price too high
Price too low400PRICE_TOO_LOWorder price too low
Zero price400PRICE_ZEROorder price zero
Quantity too large400QTY_TOO_LARGEorder quantity too large
Quantity too small400QTY_TOO_SMALLorder quantity too small
Order value too large400VALUE_TOO_LARGEorder value too large
Order value too small400VALUE_TOO_SMALLorder value too small
Post-Only order would match immediately400POST_ONLY_MATCHpost only order would match
Account suspended400ACCOUNT_SUSPENDEDorder account suspended
User suspended400USER_SUSPENDEDorder user suspended
Active orders limit exceeded400ACTIVE_ORDERS_LIMIT_EXCEEDEDactive orders limit exceeded
Duplicate clientOrderId400DUPLICATE_CLIENT_ORDER_IDduplicate client order id
Concentration limit restriction400CONCENTRATION_LIMIT_RESTRICTEDorder rejected due to concentration limit restriction
Trading closed for instrument400TRADING_NOT_AVAILABLEtrading is closed for this instrument
Invalid settlement currency400INVALID_SETTLEMENT_CURRENCYorder invalid settlement currency
gRPC place order business error (code != 0)400GRPC_ORDER_ERROR{resp.message}
gRPC timeout (DEADLINE_EXCEEDED)408API_TIMEOUTA service timed-out.
gRPC service unavailable (UNAVAILABLE)500SERVICE_TEMPORARILY_UNAVAILABLEservice is temporarily not available
Matching engine unavailable (SharedMemoryTableFull, etc.)400ENGINE_UNAVAILABLEengine is temporarily unavailable - try later
MG API timeout (ECONNABORTED)408API_TIMEOUTA service timed-out.
MG API internal error500INTERNAL_SERVER_ERRORinternal server error

2.2 GET /api/v4/order — Query Orders

Error ScenarioHTTP Statuserror.nameerror.message
Order not found400ORDER_NOT_FOUNDorder not found
Invalid symbol parameter400INVALID_SYMBOLinvalid symbol
MG API timeout408API_TIMEOUTA service timed-out.
Downstream service error500INTERNAL_SERVER_ERRORinternal server error

2.3 DELETE /api/v4/order — Cancel Order

Error ScenarioHTTP Statuserror.nameerror.message
Missing orderId or clientOrderId400REQUIRED_AT_LEAST_ONE_OF_ORDER_ID_OR_CLIENT_ORDER_IDrequired at least one of order id or client order id
Invalid orderId400INVALID_ORDER_IDinvalid order id
Order already cancelled400ALREADY_CANCELLEDorder already cancelled
Order already fully matched400ALREADY_MATCHEDorder already matched
Order already amended400ALREADY_AMENDEDorder already amended
Order not found400ORDER_NOT_FOUNDorder not found
gRPC cancel order business error (code != 0)400GRPC_ORDER_ERROR{resp.message}
gRPC timeout408API_TIMEOUTA service timed-out.
gRPC service unavailable500SERVICE_TEMPORARILY_UNAVAILABLEservice is temporarily not available

2.4 DELETE /api/v4/order/all — Cancel All Orders

Error ScenarioHTTP Statuserror.nameerror.message
gRPC cancel all business error (code != 0)400GRPC_ORDER_ERROR{resp.message}
gRPC timeout408API_TIMEOUTA service timed-out.
gRPC service unavailable500SERVICE_TEMPORARILY_UNAVAILABLEservice is temporarily not available
MG engine unavailable400ENGINE_UNAVAILABLEengine is temporarily unavailable - try later

3. Execution Query Endpoints

3.1 GET /api/v4/execution — Query Executions

Error ScenarioHTTP Statuserror.nameerror.message
Invalid symbol parameter400INVALID_SYMBOLinvalid symbol
acctGroupUuid exceeds max length400BAD_REQUESTparameter acctGroupUuid exceeds max length
Upstream spot-rest 4xx error400BAD_REQUEST{upstream message}
MG API timeout408API_TIMEOUTA service timed-out.
Downstream service error500INTERNAL_SERVER_ERRORinternal server error

3.2 GET /api/v4/execution/order — Query Executions by Order

Error ScenarioHTTP Statuserror.nameerror.message
Missing orderId or clientOrderId400REQUIRED_ONE_OF_ORDER_ID_OR_CLIENT_ORDER_IDrequired exclusively one of order id or client order id
Invalid orderId400INVALID_ORDER_IDinvalid order id
Invalid clientOrderId400INVALID_CLIENT_ORDER_IDinvalid client order id
MG API timeout408API_TIMEOUTA service timed-out.
Downstream service error500INTERNAL_SERVER_ERRORinternal server error

4. Market Trades (Public)

4.1 GET /api/v4/trade — Query Market Trades

Error ScenarioHTTP Statuserror.nameerror.message
Missing symbol parameter400INVALID_SYMBOLinvalid symbol
Symbol does not exist400INVALID_SYMBOLinvalid symbolBusiness Logic
Upstream mktdata 4xx error400BAD_REQUEST{upstream message}
MG API timeout408API_TIMEOUTA service timed-out.
Downstream service error500INTERNAL_SERVER_ERRORinternal server error

5. Order Book Endpoints

5.1 GET /api/v4/orderBook/L2 — Query Order Book

Error ScenarioHTTP Statuserror.nameerror.message
Missing symbol parameter400INVALID_SYMBOLinvalid symbol
Invalid depth parameter400INVALID_ORDER_BOOK_DEPTHinvalid order book depth
Symbol does not exist400INVALID_SYMBOLinvalid symbolBusiness Logic
MG API timeout408API_TIMEOUTA service timed-out.
Downstream service error500INTERNAL_SERVER_ERRORinternal server error

5.2 GET /api/v4/orderBook/L2/many — Batch Query Order Books

Error ScenarioHTTP Statuserror.nameerror.message
Missing symbols parameter400INVALID_SYMBOLinvalid symbol
Invalid depth parameter400INVALID_ORDER_BOOK_DEPTHinvalid order book depth
MG API timeout408API_TIMEOUTA service timed-out.
Downstream service error500INTERNAL_SERVER_ERRORinternal server error

6. Exchange Info Endpoints

6.1 GET /api/v4/instrument — Query Trading Pairs

Error ScenarioHTTP Statuserror.nameerror.message
MG API timeout408API_TIMEOUTA service timed-out.
Downstream service error500INTERNAL_SERVER_ERRORinternal server error

7. Wallet Endpoint

7.1 GET /api/v4/user/wallet — Query Wallet Balance

Error ScenarioHTTP Statuserror.nameerror.message
acctGroupUuid exceeds max length400BAD_REQUESTparameter acctGroupUuid exceeds max length
Currency not found or empty wallet400CURRENCY_NOT_FOUNDcurrency not found or empty wallet for that currency
MG API timeout408API_TIMEOUTA service timed-out.
Downstream service error500INTERNAL_SERVER_ERRORinternal server error

8. Kline Endpoint

8.1 GET /api/v4/klines — Query Kline Data

Error ScenarioHTTP Statuserror.nameerror.message
Missing symbol parameter400REQUIRED_SYMBOLsymbol is required
Missing granularity parameter400REQUIRED_GRANULARITYgranularity is required
Invalid granularity value400INVALID_GRANULARITYinvalid granularity
Invalid limit parameter400INVALID_LIMITinvalid limit
Symbol does not exist400INVALID_SYMBOLinvalid symbol
Kline service timeout408API_TIMEOUTA service timed-out.
Kline service error500INTERNAL_SERVER_ERRORinternal server error

9. Settlement Report Endpoints

9.1 POST /api/v4/settlement/fills — Query Fills Report

Error ScenarioHTTP Statuserror.nameerror.message
Invalid report period parameter400BAD_REQUEST{validation message}
Downstream service error500INTERNAL_SERVER_ERRORinternal server error

9.2 POST /api/v4/settlement/internal/fills — Internal Fills Report

Error ScenarioHTTP Statuserror.nameerror.message
Missing x-user-uuid header400BAD_REQUESTMissing required header: x-user-uuid
Invalid report period parameter400BAD_REQUEST{validation message}
Downstream service error500INTERNAL_SERVER_ERRORinternal server error

9.3 POST /api/v4/settlement/accounts — Query Account Report

Error ScenarioHTTP Statuserror.nameerror.message
Downstream service error500INTERNAL_SERVER_ERRORinternal server error

9.4 POST /api/v4/settlement/internal/accounts — Internal Account Report

Error ScenarioHTTP Statuserror.nameerror.message
Missing x-user-uuid header400BAD_REQUESTMissing required header: x-user-uuid
Downstream service error500INTERNAL_SERVER_ERRORinternal server error

9.5 POST /api/v4/settlement/transactions — Query Transactions Report

Error ScenarioHTTP Statuserror.nameerror.message
Invalid report period parameter400BAD_REQUEST{validation message}
Downstream service error500INTERNAL_SERVER_ERRORinternal server error

9.6 POST /api/v4/settlement/internal/transactions — Internal Transactions Report

Error ScenarioHTTP Statuserror.nameerror.message
Missing x-user-uuid header400BAD_REQUESTMissing required header: x-user-uuid
Invalid report period parameter400BAD_REQUEST{validation message}
Downstream service error500INTERNAL_SERVER_ERRORinternal server error

10. Health & Version

10.1 GET /api/v4/health — Health Check

Error ScenarioHTTP Statuserror.nameerror.message
Dependent service unhealthy503(no error object, returns service health status list)—

10.2 GET /api/v4/version — Version Info

This endpoint has no error scenarios and always returns 200.

15. Legacy Engine Error Code Mapping Table

The following error codes originate from the legacy matching engine.

Legacy Engine Error MessageMapped error.nameMapped error.message
OrderAccountSuspendedACCOUNT_SUSPENDEDorder account suspended
OrderImmediateNoMatchNO_LIQUIDITYorder no liquidity
OrderInsufficientCashINSUFFICIENT_HOLDINGSorder insufficient holdings
OrderInsufficientHoldingsINSUFFICIENT_HOLDINGSorder insufficient holdings
OrderInvalidCurrencyINVALID_CURRENCYorder invalid currency
OrderInvalidExpiryDateINVALID_EXPIRY_DATEorder invalid expiry date
OrderInvalidExpiryTimeINVALID_EXPIRY_TIMEorder invalid expiry time
OrderInvalidPriceINVALID_PRICEorder invalid price
OrderInvalidPriceStepINVALID_PRICE_STEPorder invalid price step
OrderInvalidQuantityINVALID_QTYorder invalid quantity
OrderInvalidQuantityStepINVALID_QTY_STEPorder invalid quantity step
OrderInvalidSettlementCurrencyINVALID_SETTLEMENT_CURRENCYorder invalid settlement currency
OrderInvalidSideINVALID_SIDEorder invalid side
OrderInvalidTypeINVALID_TYPEorder invalid type
OrderNoHoldingsNO_HOLDINGSorder no holdings
OrderPriceNegativePRICE_NEGATIVEorder price negative
OrderPriceTooHighPRICE_TOO_HIGHorder price too high
OrderPriceTooLowPRICE_TOO_LOWorder price too low
OrderPriceZeroPRICE_ZEROorder price zero
OrderQuantityTooLargeQTY_TOO_LARGEorder quantity too large
OrderQuantityTooSmallQTY_TOO_SMALLorder quantity too small
OrderStatusSetNoCancelCancelledALREADY_CANCELLEDorder already cancelled
OrderStatusSetNoCancelMatchedALREADY_MATCHEDorder already matched
OrderStatusSetNoCancelAmendedALREADY_AMENDEDorder already amended
OrderUserSuspendedUSER_SUSPENDEDorder user suspended
OrderValueTooLargeVALUE_TOO_LARGEorder value too large
OrderValueTooSmallVALUE_TOO_SMALLorder value too small
OrderPostOnlyMatchPOST_ONLY_MATCHpost only order would match
OrderAmendNotavailableAMEND_NOT_AVAILABLEorder amend not available
OrderInstrumentmarketClosedTRADING_NOT_AVAILABLEtrading is closed for this instrument
InvalidOrderALREADY_CANCELLEDorder already cancelled
CONCENTRATION_LIMIT_RESTRICTEDCONCENTRATION_LIMIT_RESTRICTEDorder rejected due to concentration limit restriction
SessionErrorSESSION_ERRORsession error
SharedMemoryTableFullENGINE_UNAVAILABLEengine is temporarily unavailable - try later
SystemAlreadyUnloadingENGINE_UNAVAILABLEengine is temporarily unavailable - try later
SystemClosedENGINE_UNAVAILABLEengine is temporarily unavailable - try later
SystemNotReadyENGINE_UNAVAILABLEengine is temporarily unavailable - try later
SystemSuspendedENGINE_UNAVAILABLEengine is temporarily unavailable - try later
UnauthorisedRequestUNAUTHORISED_REQUESTunauthorised request
UnauthorisedTransactionUNAUTHORISED_TRANSACTIONunauthorised transaction
UnauthorizedAUTH_SERVICE_UNABLE_TO_AUTHunable to auth with auth service
ForbiddenACCESS_DENIEDaccess denied
Not FoundNOT_FOUNDnot found
Method Not AllowedMETHOD_NOT_ALLOWEDmethod not allowed
DUPLICATE_CLIENT_ORDER_IDDUPLICATE_CLIENT_ORDER_IDduplicate client order id
INTERNAL_SERVER_ERRORINTERNAL_SERVER_ERRORinternal server error
INVALID_ACCOUNTINVALID_ACCOUNT_CODEinvalid account code
INVALID_EXTERNAL_ACCOUNTINVALID_EXTERNAL_ACCOUNTinvalid external account
INVALID_INSTRUMENTINVALID_CURRENCYinvalid currency
INVALID_INSTRUMENT_MARKETINVALID_SYMBOLinvalid symbol
INVALID_ORDER_IDINVALID_ORDER_IDinvalid order id
INVALID_ORDER_QTYINVALID_QTYinvalid order quantity
INVALID_ORDER_TYPEINVALID_TYPEinvalid order type
INVALID_PRICEINVALID_PRICEinvalid order price
INVALID_SIDEINVALID_SIDEinvalid order side
INVALID_TIME_IN_FORCEINVALID_TIME_IN_FORCEinvalid order time in force
INVALID_EXEC_INSTINVALID_EXEC_INSTinvalid order execution instruction
REQUIRED_ACCOUNT_CODEREQUIRED_ACCOUNT_CODEaccount code is required
REQUIRED_INSTRUMENT_MARKETREQUIRED_SYMBOLsymbol is required
REQUIRED_PRICEREQUIRED_PRICEorder price is required
REQUIRED_ORDER_IDREQUIRED_ORDER_IDorder id is required
REQUIRED_ORDER_QTYREQUIRED_QTYorder quantity is required
ORDER_NOT_FOUNDORDER_NOT_FOUNDorder not found
ACTIVE_ORDERS_LIMIT_EXCEEDEDACTIVE_ORDERS_LIMIT_EXCEEDEDactive orders limit exceeded
UNEXPECTED_ERRORUNEXPECTED_ERRORunexpected error
MAJOR_VERSION_MISMATCHMAJOR_VERSION_MISMATCHmajor version mismatch
VERSION_CANNOT_PARSEVERSION_CANNOT_PARSEversion cannot parse

16. HTTP Status Code Summary

HTTP StatusMeaningTypical Scenarios
400Bad RequestParameter validation failure, business logic errors, downstream business code non-zero
401UnauthorizedAuthentication failure (missing headers, invalid signature, expired tonce)
403ForbiddenInsufficient permissions (API Key lacks order permission, auth-service denied)
404Not FoundUnregistered route
408Request TimeoutMG API timeout, gRPC DEADLINE_EXCEEDED
410GoneDeprecated endpoints (CoinGecko/CoinMarketCap)
429Too Many RequestsRate limit exceeded
500Internal Server ErrorInternal system error, downstream service unavailable
503Service UnavailableHealth check failed (dependent service unhealthy)

Updated about 1 month ago

Did this page help you?

Updated about 1 month ago

Did this page help you?