Error Handling

Use this guide to parse OBSDN API errors, look up error metadata, and decide whether a request should be retried.

Error Response Format

All API errors return an envelope with an error object and a request ID:

{
  "error": {
    "code": "InvalidArgument",
    "message": "E0101_InvalidArgument: The provided input is invalid."
  },
  "request_id": "5b8a..."
}

Field	Description
`error.code`	gRPC status code name (e.g., `InvalidArgument`, `Unauthenticated`, `NotFound`)
`error.message`	Human-readable message; for application-level errors begins with the error reference (e.g., `E0101_InvalidArgument: ...`)
`request_id`	Server-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..."
}

Error Reference Format

Error messages follow the pattern: E{CODE}_{Reference}: {Description}

Example: E0101_InvalidArgument: The provided input is invalid.

E0101 - Numeric error code
InvalidArgument - Machine-readable reference
The provided input is invalid. - Human-readable message

Error Categories

Category	Description
`auth`	Authentication and authorization errors
`validation`	Request validation failures
`trading`	Order and trade execution errors
`account`	Account and balance issues
`market`	Market data and product errors
`rate_limit`	Rate limiting errors
`funding`	Funding and withdrawal errors
`system`	Internal system errors

Looking Up Error Codes

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
`cat`	Filter by category (`auth`, `validation`, `trading`, `account`, `market`, `rate_limit`, `funding`, `system`)
`ref`	Filter by full error reference (e.g., `E0101_InvalidArgument`)

Error Code Response

{
  "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": "..."
}

Response Fields

Field	Description
`ref`	Full error reference identifier
`code`	Short error code
`cat`	Error category
`grpc_code`	Corresponding gRPC code name (e.g., `InvalidArgument`, `Unauthenticated`)
`title`	Brief summary for UI display
`msg`	User-friendly error description
`action`	Suggested handling (`retry`, `redirect_login`, `contact_support`, `none`)
`sev`	Severity level (`error`, `warning`, `info`)
`retry_alwd`	Whether the operation can be retried
`http_st`	Corresponding HTTP status code

Common Errors

Authentication Errors

Code	Reference	Cause
E0001	AuthRequired	Authentication required
E0003	PermissionDenied	Permission denied for this action
E0004	ReadOnlyKey	API key is read-only; operation requires a full key
E0005	InvalidAPIKey	API key is invalid
E0006	InvalidSignature	Request signature is invalid

Validation Errors

Code	Reference	Cause
E0101	InvalidArgument	Invalid input provided
E0102	InvalidFormat	Input format is invalid
E0103	InvalidSymbol	Trading symbol is invalid
E0104	InvalidCursor	Pagination cursor is invalid or expired
E0105	ValueOutOfRange	Value outside allowed range

Trading Errors

Code	Reference	Cause
E0201	InsufficientBalance	Not enough balance for operation
E0202	OrderLimitExceeded	Maximum open orders reached
E0203	InvalidOrderType	Order type not allowed for this symbol
E0204	InvalidStopPrice	Stop price is invalid for this order

Account Errors

Code	Reference	Cause
E0301	UserNotFound	Requested user not found
E0302	AccountRestricted	Account is restricted from this operation

Market Errors

Code	Reference	Cause
E0401	SymbolNotTrading	Symbol is not currently available for trading
E0402	MarketClosed	Market is currently closed

Rate Limit Errors

Code	Reference	Cause
E0501	RateLimitExceeded	Too many requests
E0502	TooManyRequests	Request limit exceeded

When you receive a rate limit error, check the Retry-After header for when to retry.

Funding Errors

Code	Reference	Cause
E0601	WithdrawalSuspended	Withdrawals are temporarily suspended
E0602	MinAmountNotMet	Amount is below the minimum required

System Errors

Code	Reference	Cause
E0701	InternalError	Internal error; retry the request
E0702	ServiceUnavailable	Service is temporarily unavailable
E0703	DatabaseError	Database error; retry the request

Handling Guidance

Parse error references - extract the error ref from error.message for programmatic handling
Use the error-codes API - build a local cache from GET /error-codes on startup
Check retry_alwd - retry only operations that explicitly allow it
Handle action - implement flows for redirect_login and contact_support
Log request_id - include it (and the full error ref) when reporting issues