Error Codes

This document provides a comprehensive reference for all error codes in the Hydra API.

gRPC Status Codes

Hydra uses standard gRPC status codes. All errors follow this format:

{
  "code": 3,
  "message": "invalid asset id",
  "details": []
}

Common Status Codes

OK (0)

Description: Success - no error

When it occurs: Successful operation

Action: None required

CANCELLED (1)

Description: Operation was cancelled

When it occurs:

• Client cancelled request
• Stream was closed

Action: Retry if needed

UNKNOWN (2)

Description: Unknown error

When it occurs:

• Unexpected server error
• Unhandled exception

Action: Check request parameters, contact support if persists

INVALID_ARGUMENT (3)

Description: Client specified an invalid argument

Common causes:

• Invalid asset ID format
• Invalid network parameters
• Malformed request data
• Out-of-range values

Examples:

// Error: invalid asset id
{
  "code": 3,
  "message": "invalid asset id"
}

// Error: invalid network
{
  "code": 3,
  "message": "unsupported network protocol"
}

// Error: invalid amount
{
  "code": 3,
  "message": "amount must be positive"
}

Action:

• Verify asset ID format (zero-padded hash for native assets, contract address for ERC-20s — see asset.GetNativeAsset / asset.GetAssets)
• Check Network shape: { protocol, id } only — not chain_id/name
• Validate all numeric values (DecimalString is human-readable, not base units)
• Ensure required fields and one-of variants are present (e.g. exactly one fee_payment on Lease requests)

DEADLINE_EXCEEDED (4)

Description: The request ran out of time, and the operation may still have completed.

Don't read it as a failure. A read can simply be retried; for a write — a payment, an order, a channel operation — check whether it took effect before sending it again. A request that ran out of time without doing anything answers UNAVAILABLE instead, which is safe to retry.

Three LiquidityService RPCs are exempt from that cap — RequestChannelLiquidity, RequestChannelRelease and RequestChannelLeaseExtension. Each waits for an on-chain channel operation to be observed, which outlives 30 s on every supported network; they rely on their own internal deadlines instead. Set a client deadline generous enough for a confirmation on those three, or you will abandon a request whose fee has already been paid.

Action:

• Retry with exponential backoff — only if the RPC is idempotent; see Idempotency & Retry Safety
• Give chain-bound calls a client deadline measured in minutes, not seconds
• For anything you want to watch rather than wait on, use the streaming endpoints

A timeout is not a rollback. The operation may have completed server-side after your deadline fired. For a write, verify before retrying.

NOT_FOUND (5)

Description: Requested resource not found

Common causes:

• Transaction doesn't exist
• Order not found
• Channel doesn't exist
• Payment not found

Examples:

// Error: transaction not found
{
  "code": 5,
  "message": "transaction not found: abc123..."
}

// Error: order not found
{
  "code": 5,
  "message": "order not found: order_xyz789"
}

Action:

• Verify resource ID is correct
• Check that resource exists on the specified network
• Ensure resource hasn't been deleted

ALREADY_EXISTS (6)

Description: Resource already exists

When it occurs:

• Attempting to create duplicate resource
• Market already initialized
• Channel already opened
• orderbook.CreateOrder of a different order under a client_order_id that already names one (prefix client_order_id_taken)

Examples:

{
  "code": 6,
  "message": "market already initialized"
}

Action:

• Check if resource already exists
• Use update/modify operations instead of create

PERMISSION_DENIED (7)

Description: Caller doesn't have permission

When it occurs:

• Authentication failure
• Insufficient permissions
• Attempting to access another user's resource

Action:

• Verify authentication credentials
• Check API key permissions
• Ensure you own the resource

RESOURCE_EXHAUSTED (8)

Description: Resource has been exhausted

Common causes:

• Insufficient balance
• No liquidity available
• Lease capacity exceeded
• Channel capacity full

Examples:

// Error: insufficient balance
{
  "code": 8,
  "message": "insufficient onchain balance"
}

// Error: no liquidity
{
  "code": 8,
  "message": "no liquidity available in orderbook"
}

// Error: lease capacity
{
  "code": 8,
  "message": "lease amount exceeds available liquidity"
}

Action:

• Check balance before operations
• Add funds to wallet
• Try smaller amount
• Wait for liquidity to become available

FAILED_PRECONDITION (9)

Description: Operation rejected due to system state

Common causes:

• Channel not active yet
• Market not initialized
• Asset not supported
• Duration out of allowed range

Examples:

// Error: channel not ready
{
  "code": 9,
  "message": "channel not active for sending"
}

// Error: market not initialized
{
  "code": 9,
  "message": "market not initialized for this pair"
}

// Error: duration invalid
{
  "code": 9,
  "message": "lease duration below minimum"
}

Action:

• Wait for prerequisite conditions
• Initialize required resources first
• Check state before operations
• Verify parameter ranges

ABORTED (10)

Description: Operation was aborted

When it occurs:

• Concurrent modification conflict
• Transaction conflict
• Order already cancelled

Action: Retry operation

OUT_OF_RANGE (11)

Description: Operation outside valid range

Common causes:

• Amount too large or too small
• Fee rate invalid
• Duration out of range

Action:

• Check minimum/maximum values
• Adjust parameters to valid range

UNIMPLEMENTED (12)

Description: Operation not implemented

When it occurs:

• Feature not yet available
• Endpoint deprecated
• Network not supported

Action:

• Check API documentation for supported features
• Use alternative endpoint

INTERNAL (13)

Description: Internal server error

When it occurs:

• Database error
• Backend service failure
• Unexpected server condition

Action:

• Retry with exponential backoff
• Contact support if persists

UNAVAILABLE (14)

Description: Service temporarily unavailable

Common causes:

• Service maintenance
• Network issues
• Backend overload
• A wait inside Hydra App ran out before the operation was sent — for a peer, a chain provider, a lock. The message may say "timeout" or "deadline"; nothing took effect, and the request may be sent again

Action:

• Retry with exponential backoff
• Check status page
• Wait and retry

DATA_LOSS (15)

Description: Unrecoverable data loss

When it occurs: Rare - serious server issue

Action: Contact support immediately

UNAUTHENTICATED (16)

Description: Request lacks valid authentication

When it occurs:

• Missing authentication
• Invalid credentials
• Expired session

Action:

• Provide authentication credentials
• Refresh authentication token
• Check API key is valid

Error Handling Best Practices

1. Implement Retry Logic — for idempotent RPCs only

⚠️ Use this helper only for Get*, Estimate*, and stream-reconnect calls. Wrapping SendTransaction, OpenChannel, CreateOrder, etc. in a blind retry can cause double-execution. See Idempotency & Retry Safety for the full rules.

async function withRetry<T>(
  operation: () => Promise<T>,
  maxRetries: number = 3,
  baseDelay: number = 1000
): Promise<T> {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await operation()
    } catch (error: any) {
      const code = error.code

      // Don't retry client errors (INVALID_ARGUMENT, NOT_FOUND, PERMISSION_DENIED,
      // OUT_OF_RANGE, UNIMPLEMENTED, UNAUTHENTICATED, FAILED_PRECONDITION)
      if ([3, 5, 7, 9, 11, 12, 16].includes(code)) {
        throw error
      }

      // Retry on transient errors (DEADLINE_EXCEEDED, UNAVAILABLE) and INTERNAL
      if ([4, 13, 14].includes(code)) {
        const delay = baseDelay * Math.pow(2, i) + Math.floor(Math.random() * 500)
        console.log(`Retry ${i + 1}/${maxRetries} after ${delay}ms`)
        await new Promise(resolve => setTimeout(resolve, delay))
        continue
      }

      throw error
    }
  }

  throw new Error('Max retries exceeded')
}

// ✅ Safe — Get* is idempotent
const balance = await withRetry(() => walletClient.getBalance(request, {}))

// ❌ DANGEROUS — SendTransaction is NOT idempotent.
//    A DEADLINE_EXCEEDED retry can broadcast twice.
//    Use the verify-before-retry pattern from the Idempotency section.
// const tx = await withRetry(() => clientClient.sendTransaction(request, {}))

2. Graceful Error Handling

async function safeGetBalance(
  client: WalletServiceClient,
  network: Network,
  assetId: string
): Promise<Balance | null> {
  try {
    const request = new GetBalanceRequest()
    request.setNetwork(network)
    request.setAssetId(assetId)

    const response = await client.getBalance(request, {})
    return response.getBalance()
  } catch (error) {
    switch (error.code) {
      case 3:
        console.error('Invalid asset ID:', assetId)
        return null

      case 5:
        console.error('Asset not found:', assetId)
        return null

      case 14:
        console.warn('Service unavailable, retrying...')
        // Implement retry logic
        return null

      default:
        console.error('Unexpected error:', error)
        throw error
    }
  }
}

3. Check Preconditions

async function sendPaymentSafely(
  walletClient: WalletServiceClient,
  nodeClient: NodeServiceClient,
  network: Network,
  assetId: string,
  amount: string
) {
  // Check balance first
  const balanceReq = new GetBalanceRequest()
  balanceReq.setNetwork(network)
  balanceReq.setAssetId(assetId)

  const balanceResp = await walletClient.getBalance(balanceReq, {})
  // Size a single payment off max_sendable, not free_local — a per-payment
  // ceiling can bind below the balance.
  const available = balanceResp.getBalance()?.getOffchain()?.getMaxSendable()?.getValue()

  // Amounts are decimal strings in whole units — compare as decimals, not BigInt.
  if (new Big(available || '0').lt(new Big(amount))) {
    throw new Error('Insufficient balance')
  }

  // Proceed with payment
  const paymentReq = new SendPaymentRequest()
  // ... configure payment
  return await nodeClient.sendPayment(paymentReq, {})
}

4. User-Friendly Messages

function getUserFriendlyError(error: any): string {
  switch (error.code) {
    case 3:
      return 'Invalid input. Please check your entries.'

    case 5:
      return 'Resource not found. Please verify the ID.'

    case 8:
      if (error.message.includes('balance')) {
        return 'Insufficient funds. Please add more to your wallet.'
      }
      if (error.message.includes('liquidity')) {
        return 'Not enough liquidity available. Try a smaller amount.'
      }
      return 'Resource limit exceeded.'

    case 9:
      return 'Operation cannot be completed right now. Please try again later.'

    case 14:
      return 'Service temporarily unavailable. Please try again in a moment.'

    default:
      return 'An unexpected error occurred. Please try again.'
  }
}

// Usage in UI
try {
  await client.someOperation(request, {})
} catch (error) {
  alert(getUserFriendlyError(error))
}

Service-Specific Errors

Wallet Service

Orderbook Service

Swap Service

Most simple-swap refusals are not errors at all. EstimateSimpleSwap succeeds and returns a SimpleSwapEstimate variant — no_liquidity, fees_higher_than_amount, lease_too_big, insufficient_sending_balance, insufficient_native_balance. Branch on the one-of; a switch that only handles the three success arms will misreport every one of these.

Node Service

Placement rejections (Orderbook)

Added 2026-08-13.

When the hub refuses an order, it encodes the reason in a stable, parseable message so an SDK can react without scraping prose:

<prefix>: key=value key=value — human tail

Match on the prefix and the key=value tokens only — never on the human tail, which is free text and may change. The gRPC status code is deliberately not part of the contract; the prefix is.

Anything not matching this closed set — including every message from a pre-2026-08-13 hub — is unclassified and should be treated as an opaque error, exactly as before.

The three sub-economic prefixes were renamed on 2026-09-16, and their keys with them. They were below_floor_budget and below_floor_count when this page was first written. A parser matching the old names now falls through to unclassified — which is safe (the order is still refused, and the refusal is still retryable) but loses the numbers that say what to do about it. The amounts are force-closure costs, not trade notionals: see Get Sub-Economic Policy for what they are measured in and how to predict a refusal instead of discovering it.

All three are retryable and none of them invalidates cached MarketInfo. sub_economic_client_limit and sub_economic_venue_limit clear as your in-flight small swaps settle; sub_economic_htlc_cap clears as their HTLCs resolve.

Only below_minimum invalidates your cached MarketInfo. It means the hub's live minimums moved past your cached view, so refetch GetMarketInfo and resize from the min_place= in the rejection — that value is authoritative, the min_place_* snapshot in MarketInfo is only advisory. below_best_fill does not: no minimum moved, the order met a resting order it is too small for.

market_state does not qualify: the market's state is what changed, and the market_info event on the market stream carries the new one the moment it changes — no refetch needed.

HTLC & Preimage Service

Liquidity Service (Lease API)

Watch-Only Node Service

Client Service

Pricing Service

Idempotency & Retry Safety

A bot must know which RPCs are safe to retry blindly after a DEADLINE_EXCEEDED or transient UNAVAILABLE.

Safe to retry (read-only, idempotent)

Retry only after checking server state first

These RPCs are not idempotent. After a DEADLINE_EXCEEDED you may have triggered the action without seeing the response. Verify before retrying:

Never auto-retry

Application-level idempotency keys

One RPC does take an idempotency token: orderbook.CreateOrder. Set client_order_id (your own string, max 64 chars) and it names that one order, while the order lives and for a retention period after it ends (24 hours by default). A retry of the same order under it gets the original answer — its order_id, and what its placement released — even when the order has ended meanwhile, instead of placing a second order; a different order under it is refused with client_order_id_taken. Read an open order back with GetOrderByClientId. Use it on every retry-prone order path — it is strictly better than any verify-then-retry dance.

Everything else needs an action ID at the application level:

1. Generate a UUID for each high-level action (e.g. "place 0.1 BTC sell at $67k").
2. Persist (action_id, status: pending|done|failed) on disk before calling the RPC.
3. After the RPC returns or after a verification check, update the status.
4. On startup, replay any pending actions: query the relevant Get* RPC, decide if the action completed, and update.

For order placement, the simplest correct scheme is to make client_order_id be your action_id: replaying a pending action then converges on the same order rather than creating a second one.

Debugging Tips

1. Enable verbose logging - Log all requests and responses
2. Check error.message - Contains detailed error information
3. Verify request format - Use protobuf debugging tools
4. Test with small amounts - Use minimal values when debugging
5. Check network status - Ensure blockchain is synced
6. Monitor rate limits - Avoid excessive requests

← Back to Setup Guide | Next: JSON-RPC →