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 request: unknown sending asset",
  "details": ["<one hydra_app.ErrorDetail, below>"]
}

The error detail

(2026-10-14) An error Hydra App answers a call with carries, beside its code and its message, an ErrorDetail whenever the node knows more than the two say: every refusal of its own — including a field missing, one that does not parse, a record it holds none of, and a call this build does not offer — every failure a network's node gives a reason for — a balance or a channel short of what the call needs, a peer not connected, a chain out of reach, a refused fee bump — and every failure it can say more of. A failure it relays from a service without a reason, and an error the transport answers before a method runs (a body that does not decode, a method that does not exist), carry none.

gRPC carries it in the status details (the grpc-status-details-bin trailer): a google.rpc.Status with the status's own code and message, holding one Any of type type.googleapis.com/hydra_app.ErrorDetail, defined in error.proto of the /proto download. JSON-RPC carries it as the error's data, in the JSON mapping — enum values by name, fields in camelCase, absent fields left out:

{
  "code": -32602,
  "message": "Invalid request: unknown sending asset",
  "data": {
    "reason": "FAILURE_REASON_UNKNOWN_ASSET",
    "metadata": { "side": "sending" }
  }
}

The code and the message say what they always did, so a client that reads none of this is exactly as well off as before. Match on reason rather than on the message: messages are written for people, and their wording changes. A message is cut at 2 KiB, so the details fit beside it within the trailers' limit; a failure logged under an error_id is logged whole.

Python (grpcio with grpcio-status):

from grpc_status import rpc_status
import error_pb2  # generated from error.proto

def error_detail(error):  # error: grpc.RpcError
    status = rpc_status.from_call(error)
    for packed in status.details if status else []:
        if packed.Is(error_pb2.ErrorDetail.DESCRIPTOR):
            detail = error_pb2.ErrorDetail()
            packed.Unpack(detail)
            return detail
    return None

Rust (hydra-app-types): hydra_app_types::error_detail::error_detail(status.details()).

Reasons

Each reason is answered with the code below. A refusal of the venue's keeps the code the venue chose, which the venue does not fix for its prefixes; and a failure that may still take effect, or that a retry clears, is answered with DEADLINE_EXCEEDED, ABORTED or UNAVAILABLE whatever its reason. A client built before a reason was added reads a number it does not know: read the code and the message then.

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.

The server's request deadline is 30 s per call. (2026-10-14) Over JSON-RPC it bounds each call on its own, wherever the call arrives: every call of a batch has its own 30 s, over HTTP or over a WebSocket. A call cut off there answers its own JSON-RPC error -32002 — over HTTP inside an ordinary 200 response, never an empty-bodied HTTP 504 — while the batch's other calls answer as usual. See the request deadline on JSON-RPC.

Three LiquidityService RPCs are exempt from that deadline — the deprecated RequestChannelLiquidity, RequestChannelRelease and RequestChannelLeaseExtension, over gRPC and (2026-10-14) over JSON-RPC alike. Each waits until the liquidity service has carried the request out, which on the on-chain fee rail means waiting through the fee transfer's confirmations: past 30 s, minutes on Ethereum. Set a client deadline of minutes on those three, or you will abandon a request whose fee has already been paid. (2026-10-14) A JSON-RPC subscription call is exempt too: it answers once its subscription is accepted.

(2026-10-14) Their replacements — SubmitChannelLiquidityRequest, SubmitChannelReleaseRequest and SubmitChannelLeaseExtensionRequest — are not exempt. They answer once your node has settled its part of the fee, normally within seconds, and the request is then followed to its end; see Submitting and following a request.

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.

Recovering a Submit* call that was cut off. (2026-10-14) The request may already have been made: the submission runs on in your node after its caller is gone. Send the same request again under the same client_request_id — it answers with the request already made, waiting for the first call if that is still running, and makes the request only if none was made. GetLiquidityRequest by the id reads it without submitting. Without an id, find the request on SubscribeLiquidityRequests or in GetFeePayments before you submit again. See client_request_id.

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)
• (2026-10-14) A liquidity.Submit* call of a different request under a client_request_id that already names one (client_request_id_taken: payment_uuid=…, naming that request — see Liquidity Service)

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: A limit on how much of something you may use at once is reached

Common causes:

• A stream already has as many subscribers as it takes (TOO_MANY_SUBSCRIBERS)
• Your referral quota is used up (REFERRAL_QUOTA_EXHAUSTED)
• The hub or the liquidity service refuses a request for a quota of its own — a rate limit — and Hydra App passes its code on

A balance, a channel or a liquidity pool too small for the request is not this code: it is FAILED_PRECONDITION (9).

Examples:

// Error: a stream with no room for another subscriber
{
  "code": 8,
  "message": "too many subscribers"
}

Action:

• Close a subscription you no longer read before opening another
• Back off and retry later: a quota frees up as earlier requests complete

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
• Not enough balance on chain or in a channel (INSUFFICIENT_BALANCE, INSUFFICIENT_NATIVE_BALANCE, INSUFFICIENT_CHANNEL_BALANCE), and any refusal whose wording says something is insufficient
• No liquidity for the request (NO_LIQUIDITY), or a lease larger than what is available (LEASE_TOO_LARGE)

Examples:

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

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

// 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
• Add funds, or try a smaller amount, where a balance or liquidity falls short

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
• Network not supported

A deprecated method is not this code: it keeps answering as before until it is removed.

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:
      return 'Too many requests at once. Please try again later.'

    case 9:
      if (error.message.includes('insufficient')) {
        return 'Insufficient funds. Please add more, or try a smaller amount.'
      }
      if (error.message.includes('liquidity')) {
        return 'Not enough liquidity available. Try a smaller amount.'
      }
      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.

(2026-10-14) Hydra App answers an unclassified refusal with the hub's own code — INVALID_ARGUMENT, NOT_FOUND, ALREADY_EXISTS, FAILED_PRECONDITION or RESOURCE_EXHAUSTED — unless its wording names a condition that has a code of its own: a node that is not connected to the hub is still UNAVAILABLE. Over JSON-RPC that is -32602, -32004, -32005, -32010 or -32003. Before, such a refusal reached you as INTERNAL (-32603).

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)

(2026-10-14) A request the liquidity service refuses with INVALID_ARGUMENT, NOT_FOUND, ALREADY_EXISTS, FAILED_PRECONDITION or RESOURCE_EXHAUSTED is answered with that code, the service's words in the message — unless those words name a condition that clears, such as a peer that is not connected, which keeps the code they pick. Before, Hydra App answered most of these refusals with INTERNAL.

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

orderbook.CreateOrder takes an idempotency token. 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.

(2026-10-14) So do the three liquidity.Submit* RPCs. Set client_request_id (your own string, 1 to 64 characters) and it names that one request on that network, across restarts of your node. The same request sent again under it gets the request already made, as it stands now, and pays nothing; a different request under it is refused with ALREADY_EXISTS and client_request_id_taken: payment_uuid=…, naming the request the id holds. A request the service refused leaves the id free. Read a request back by it with GetLiquidityRequest. See client_request_id.

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. (2026-10-14) For a liquidity request, make client_request_id your action_id the same way.

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 →