Error Handling API error format, lookup, and retry guidance
Use this guide to parse OBSDN API errors, look up error metadata, and decide whether a request should be retried.
All API errors return an envelope with an error object and a request ID:
{ "error" : { "code" : "InvalidArgument" , "ref" : "E0101_InvalidArgument" , "message" : "The provided input is invalid." }, "request_id" : "5b8a..." } Field Description error.codegRPC status code name (e.g., InvalidArgument, Unauthenticated, NotFound) error.refMachine-readable error reference from the error catalog (e.g., E0101_InvalidArgument); may be absent for low-level transport errors error.messageHuman-readable error description request_idServer-generated request identifier; also returned in the X-Request-Id response header
Successful responses follow the same envelope pattern with the payload under data:
{ "data" : { /* response payload */ }, "request_id" : "5b8a..." } The ref field follows the pattern E{CODE}_{Name} and maps directly to the error catalog available via GET /error-codes.
Example: E0101_InvalidArgument
E0101 - Numeric error codeInvalidArgument - Machine-readable name
Use ref (not message) for programmatic error handling. The message field is human-readable and may change without notice.
Category Description authAuthentication and authorization errors validationRequest validation failures tradingOrder and trade execution errors accountAccount and balance issues marketMarket data and product errors rate_limitRate limiting errors fundingFunding and withdrawal errors systemInternal system errors
Use the Error Codes API to look up error metadata:
# Get all error codes curl https://api.obsdn.trade/error-codes # Filter by category curl "https://api.obsdn.trade/error-codes?cat=trading" # Look up specific error curl "https://api.obsdn.trade/error-codes?ref=E0101_InvalidArgument" Query Description catFilter by category (auth, validation, trading, account, market, rate_limit, funding, system) refFilter by full error reference (e.g., E0101_InvalidArgument)
{ "data" : { "errs" : [ { "ref" : "E0101_InvalidArgument" , "code" : "E0101" , "cat" : "validation" , "grpc_code" : "InvalidArgument" , "title" : "Invalid Input" , "msg" : "The provided input is invalid." , "action" : "none" , "sev" : "warning" , "retry_alwd" : true , "http_st" : 400 } ] }, "request_id" : "..." } Field Description refFull error reference identifier codeShort error code catError category grpc_codeCorresponding gRPC code name (e.g., InvalidArgument, Unauthenticated) titleBrief summary for UI display msgUser-friendly error description actionSuggested handling (retry, redirect_login, contact_support, none) sevSeverity level (error, warning, info) retry_alwdWhether the operation can be retried http_stCorresponding HTTP status code
Code Reference HTTP Cause E0001 E0001_AuthRequired 401 Authentication required E0002 E0002_InternalRequired 403 Endpoint requires internal access E0003 E0003_PermissionDenied 403 Permission denied for this action E0004 E0004_ReadOnlyKey 403 this operation requires a full API key E0005 E0005_InvalidAPIKey 401 API key is invalid E0006 E0006_InvalidSignature 401 Request signature is invalid
Code Reference Cause E0101 E0101_InvalidArgument Invalid input provided E0102 E0102_InvalidFormat Input format is invalid E0103 E0103_InvalidSymbol Trading symbol is invalid E0104 E0104_InvalidCursor Pagination cursor is invalid or expired E0105 E0105_ValueOutOfRange Value outside allowed range E0106 E0106_AlreadyExists Entity already exists
Code Reference Cause E0201 E0201_InsufficientBalance Not enough balance for operation E0202 E0202_OrderLimitExceeded Maximum open orders reached E0203 E0203_InvalidOrderType Order type not allowed for this symbol E0204 E0204_InvalidStopPrice Stop price is invalid for this order
Code Reference Cause E0301 E0301_UserNotFound Requested user not found E0302 E0302_AccountRestricted Account is restricted from this operation
Code Reference Cause E0401 E0401_SymbolNotTrading Symbol is not currently available for trading E0402 E0402_MarketClosed Market is currently closed E0403 E0403_InvalidTimestamp Request timestamp is outside the allowed window
Order placement and cancellation are gated by the market's lifecycle stage (see Market Lifecycle ). When an action is not allowed in the current stage, the API returns InvalidArgument with one of these messages, where {id} is the market identifier from the request:
Message Stage Meaning only post-only orders are allowed in {id} marketpre-launch Only maker (post-only) orders are accepted market {id} is in wind-down mode, only reduce-only orders allowedwinding down Only position-reducing orders are accepted market {id} is haltedhalted No new orders; cancellations still work market {id} is outside trading hoursoff-hours Underlying exchange is closed; cancellations still work market {id} is being delisteddelisting Market is being delisted; all user orders blocked market {id} has been delisteddelisted All operations blocked, including cancellation
Code Reference Cause E0501 E0501_RateLimitExceeded Too many requests E0502 E0502_TooManyRequests Request limit exceeded
When you receive a rate limit error, implement your own exponential backoff before retrying.
Code Reference Cause E0601 E0601_WithdrawalSuspended Withdrawals are temporarily suspended E0602 E0602_MinAmountNotMet Amount is below the minimum required
Code Reference Cause E0701 E0701_InternalError Internal error; retry the request E0702 E0702_ServiceUnavailable Service is temporarily unavailable E0703 E0703_DatabaseError Database error; retry the request E0704 E0704_ExchangeDegraded Exchange cannot process writes right now; retry shortly
Use error.ref - match on the ref field for programmatic error handling; it maps to the error catalogUse the error-codes API - build a local cache from GET /error-codes on startupCheck retry_alwd - retry only operations that explicitly allow itHandle action - implement flows for redirect_login and contact_supportLog request_id - include it (and ref) when reporting issues