Error Handling

This guide explains how to handle errors from the Moonbase API and use the error codes reference for debugging.

Error Response Format

All API errors return an error object:

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

Field	Description
`error.code`	Error code (e.g., `InvalidArgument`, `Unauthenticated`, `NotFound`)
`error.message`	Error reference and description

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 get detailed information about any error:

# Get all error codes
curl https://api.dev.mbhq.net/v1/error-codes

# Filter by category
curl https://api.dev.mbhq.net/v1/error-codes?category=trading

# Look up specific error
curl https://api.dev.mbhq.net/v1/error-codes?ref=E0101_InvalidArgument

Error Code Response

{
  "data": {
    "errors": [
      {
        "ref": "E0101_InvalidArgument",
        "code": "E0101",
        "category": "validation",
        "grpc_code": "InvalidArgument",
        "title": "Invalid Input",
        "message": "The provided input is invalid.",
        "action": "none",
        "severity": "warning",
        "retry_allowed": true,
        "http_status": 400
      }
    ]
  }
}

Response Fields

Field	Description
`ref`	Full error reference identifier
`code`	Short error code
`category`	Error classification
`grpc_code`	Corresponding gRPC code name (e.g., `InvalidArgument`, `Unauthenticated`)
`title`	Brief summary for UI display
`message`	User-friendly error description
`action`	Suggested handling (`retry`, `redirect_login`, `contact_support`, `none`)
`severity`	Level indicator (`error`, `warning`, `info`)
`retry_allowed`	Whether the operation can be retried
`http_status`	Corresponding HTTP status code

Common Errors

Authentication Errors

Code	Reference	Cause
E0001	AuthRequired	Authentication required
E0003	PermissionDenied	Permission denied for this action
E0004	InsufficientScope	Access token missing required scope

Validation Errors

Code	Reference	Cause
E0101	InvalidArgument	Invalid input provided
E0104	InvalidSymbol	Trading symbol is invalid
E0110	ValueOutOfRange	Value outside allowed range

Trading Errors

Code	Reference	Cause
E0201	InsufficientBalance	Not enough balance for operation
E0210	OrderLimitExceeded	Maximum open orders reached
E0213	InvalidStopPrice	Invalid stop price for order

Funding Errors

Code	Reference	Cause
E0601	WithdrawalSuspended	Withdrawals temporarily suspended
E0603	MinWithdrawalAmount	Amount below minimum withdrawal limit
E0605	DailyWithdrawalLimitExceeded	Daily withdrawal limit exceeded

Rate Limit Errors

Code	Reference	Cause
E0501	RateLimitExceeded	Too many requests
E0503	OrderRateLimitExceeded	Order rate limit exceeded

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

Best Practices

Parse error references - Extract the error ref from messages for programmatic handling
Use the error-codes API - Build a local cache of error codes on startup
Check retry_allowed - Only retry operations that support it
Handle action field - Implement flows for redirect_login and contact_support
Log error details - Include the full error ref for debugging