Error Codes

Balchemy API errors arrive in more than one shape. This page documents each error envelope, all relevant HTTP status codes, and common error scenarios by domain.

Warning: A 2xx transport status does not mean the operation succeeded. Canonical failures are returned as success: false envelopes, and several trading paths return them with an HTTP 200. Always inspect the response body before treating a request as successful.

Error envelope format

REST API errors

REST responses use two envelopes. Client code must handle both.

Canonical envelope. The success field, not the HTTP status, carries the outcome. Canonical failures include request metadata when available:

{
  "success": false,
  "error": {
    "code": "PROVIDER_UNAVAILABLE",
    "message": "Provider unavailable",
    "details": {
      "retryable": true
    }
  },
  "meta": {
    "requestId": "req_123",
    "correlationId": "corr_456"
  }
}

This envelope can be returned with an HTTP 200. Treat any body containing "success": false as a failure regardless of the status code, and preserve error and meta rather than collapsing a degraded response into successful empty data.

Legacy envelope. Routes that have not been migrated still return status-coded bodies:

{
  "statusCode": 401,
  "message": "Unauthorized",
  "error": "Unauthorized"
}

For validation errors, the message field is an array of strings:

{
  "statusCode": 400,
  "message": ["message must be a string", "message should not be empty"],
  "error": "Bad Request"
}

For domain-specific service exceptions, an additional code field is included:

{
  "statusCode": 503,
  "message": "LLM provider unavailable",
  "code": "LLM_PROVIDER_UNAVAILABLE",
  "error": "Service Unavailable"
}

MCP (JSON-RPC) errors

MCP tool calls use the JSON-RPC 2.0 error format:

{
  "jsonrpc": "2.0",
  "id": "req-uuid",
  "error": {
    "code": -32603,
    "message": "Tool execution failed: insufficient balance",
    "data": {
      "tool": "trading_solana_jupiter_swap",
      "reason": "INSUFFICIENT_BALANCE"
    }
  }
}

Standard JSON-RPC error codes used by the MCP layer:

HTTP status code reference

Auth errors

Trading errors

Rows marked Soft error (200) are returned with an HTTP 200 and a failure body. A client that branches only on the transport status will read these as successful trades. Inspect the response body — a success: false envelope or a failure message field — before recording an order as placed, and never treat a soft error as a reason to resubmit without first checking order state.

MCP errors

MCP tool visibility is runtime-scoped. Use tools/list with the same Hub agent key that will call the tool; the result reflects operator-controlled exposure, key scope, and current registry metadata. Read tools, guarded trade tools, and manage/write-like controls have different replay, step-up, and policy gates.

Agent (ERC-8004) errors

Service exception codes

These codes appear in the code field for server-side service exceptions:

SDK error codes

The Agent SDK maps API errors to typed AgentSdkError codes:

Catch and inspect the code in your error handler:

import { AgentSdkError } from "@balchemyai/agent-sdk";
 
try {
  const result = await mcp.agentMarketBrief({ query: "Solana launch candidates" });
} catch (err: unknown) {
  if (err instanceof AgentSdkError) {
    switch (err.code) {
      case "auth_error":
        // Re-onboard or refresh your MCP key
        break;
      case "rate_limit_error":
        // Back off — Retry-After header value is in err.details
        break;
      case "network_error":
        // Retry with exponential backoff
        break;
    }
  }
}

The SDK applies bounded exponential backoff with jitter to network_error and rate_limit_error, and honours Retry-After when the response supplies it. execution_error is also in the SDK's default retryable set, and the exemption is narrower than it looks: the MCP client suppresses execution_error retry for tools/call only. The REST client applies the default policy to both get and post, and it converts any success: false body into an execution_error — so a canonical failure returned to a side-effecting POST is retried up to the default 3 attempts unless you say otherwise.

Warning: Supply your own shouldRetry predicate (or an outer guard) for every side-effecting REST call you make through the SDK, including identity-token revoke calls. Relying on the default policy means a success: false POST is replayed automatically.

Automatic retry is scoped to safe, idempotent read calls. Do not wrap side-effecting trade, manage, approval, withdrawal, wallet, or swap operations in an automatic replay: a network_error means the response was lost, not that the operation was rejected, and replaying it can dispatch a second order. Do not retry 401, 403, invalid request, unsupported chain, unconfigured provider, or deterministic policy and budget blocks — they fail identically on every attempt. Give each operation exactly one retry owner; if the SDK is retrying, your caller must not. For fund-sensitive calls, reconcile order state before deciding whether to send anything again. See Rate Limits for the full retry contract.

Related pages

• API Endpoints
• Rate Limits
• Tool Catalog
• SDK Getting Started
• Security