Skip to main content
Hive writes errors for the model, not just the log. Each one names what went wrong and what to do next, so an agent can recover without a human reading a stack trace.

Authentication

Sending a key that is present but wrong returns a 200 with an error envelope rather than a 401. This is deliberate and regression-tested: some MCP clients treat a 401 as a transport failure and drop the connection instead of surfacing the message.

Quota and rate

Credits and rate limits are independent. You can hit a per minute limit while well inside your monthly credits.

Tools and arguments

Most argument errors come from an agent guessing parameter names. Reading the schema first avoids nearly all of them. All three carry runtime_status: "invalid_input" in the receipt: the call is fixable by the caller, and retrying it unchanged will fail again.

Provider and runtime

A provider being unavailable is not the same as a datapoint being absent. Hive distinguishes the two so your agent does not report “no data” when the truth is “could not check”.

Handling errors in an agent

Give your agent one rule: when a call fails, read the message and act on it rather than retrying the same call. Hive’s errors say which of the above happened, and the right response differs completely between a rate limit and an invalid argument.

Error codes

Every code Hive emits, on any transport, with the anchor its doc_url points at. Generated from src/utils/errorCodes.ts; do not edit by hand.

AMBIGUOUS_TOKEN

The token name or ticker matches several tokens; the error lists the candidates. Transports: mcp, rest. Not retryable: change the request (or the credential) before calling again. Do next: Ask the user which candidate they mean, then call again with its id, or its contract and chain.

API_ERROR

The server answered with an error the CLI does not map further. Transports: cli. Not retryable: change the request (or the credential) before calling again. Do next: Read the message; it is the server’s own wording. Retry only if it says the failure is transient.

AUTH_NOT_CONFIGURED

This server has no auth backend configured; discovery still works without a credential. Transports: mcp, rest. Not retryable: change the request (or the credential) before calling again. Do next: Use the hosted endpoint, or set the auth backend env vars on this server.

AUTH_REQUIRED

The call needs an API key or an OAuth session. Transports: rest, cli. Not retryable: change the request (or the credential) before calling again. Do next: Send an API key as Authorization: Bearer <key>, or sign in (hive auth login on the CLI).

AUTH_SERVICE_UNAVAILABLE

The key service is unreachable; retry shortly. Transports: mcp, rest. Retryable: the same request can succeed later without a change. Do next: Retry in a few seconds; the key was not rejected.

BUNDLE_UNAVAILABLE

No section of the job tool could be answered; runtime_status is the first failing section’s, and the call is refunded. Transports: mcp, rest. Not retryable: change the request (or the credential) before calling again. Do next: Follow next_action; retry later only when runtime_status is rate_limited or degraded, or ask for fewer sections.

CATALOG_PAGINATION_ERROR

The tools catalog cursor is invalid; restart from the first page. Transports: rest. Not retryable: change the request (or the credential) before calling again. Do next: Restart from the first page; paginate with ?limit=250&cursor=<last tool name>.

ENDPOINT_NOT_FOUND

No REST route at that path. Transports: rest. Not retryable: change the request (or the credential) before calling again. Do next: Check the path against GET /api/openapi.json.

FEEDBACK_RATE_LIMITED

Feedback is limited to 10 messages per principal per UTC day. Transports: mcp, rest, cli. Retryable: the same request can succeed later without a change. Do next: Stop sending feedback until the reset time in the message.

GENERAL_ERROR

The CLI hit an unclassified error. Transports: cli. Not retryable: change the request (or the credential) before calling again. Do next: Rerun with --verbose to see what the CLI hit.

IDEMPOTENCY_KEY_REUSED

That idempotency_key was already used with different arguments. Transports: mcp, rest. Not retryable: change the request (or the credential) before calling again. Do next: Use a new key, or resend the original arguments unchanged.

INTERNAL_ERROR

Hive failed unexpectedly; the request id identifies the log line. Transports: mcp, rest, cli. Retryable: the same request can succeed later without a change. Do next: Retry once. If it repeats, send the request id from the receipt with report_feedback.

INVALID_API_KEY

The API key was rejected; check it in the dashboard. Transports: mcp, rest, cli. Not retryable: change the request (or the credential) before calling again. Do next: Copy the key again from the dashboard; keys start with hive_live_.

INVALID_ARGS

The CLI arguments are invalid. Transports: cli. Not retryable: change the request (or the credential) before calling again. Do next: Check hive <command> --help; hive tools info <name> prints the parameter table.

INVALID_IDEMPOTENCY_KEY

idempotency_key must be 1 to 128 characters of letters, digits, _ - : . Transports: mcp, rest. Not retryable: change the request (or the credential) before calling again. Do next: Send 1 to 128 characters of letters, digits, or _ - : . as the key.

INVALID_OAUTH_TOKEN

The OAuth token was rejected; sign in again. Transports: mcp. Not retryable: change the request (or the credential) before calling again. Do next: Sign in again in the client; the token expired or was revoked.

INVALID_REQUEST

The request body is malformed. Transports: rest. Not retryable: change the request (or the credential) before calling again. Do next: Send a JSON object body with content-type: application/json.

MISSING_PARAM

A required argument is missing. Transports: rest. Not retryable: change the request (or the credential) before calling again. Do next: Add the argument named in the message; get_api_endpoint_schema lists the required set.

NO_WALLET

The account has no credit wallet; initialize billing in the dashboard. Transports: mcp, rest, cli. Not retryable: change the request (or the credential) before calling again. Do next: Open the dashboard billing page once to initialize the credit wallet.

PAYLOAD_TOO_LARGE

The request body exceeds the size limit. Transports: rest. Not retryable: change the request (or the credential) before calling again. Do next: Split the request, or bound it with limit instead of sending the whole payload.

PROVIDER_UNAVAILABLE

The provider is not configured or is down; the receipt says which. Transports: mcp, rest, cli. Retryable: the same request can succeed later without a change. Do next: Try the route’s fallback tool once, then report the gap with report_feedback.

QUOTA_EXCEEDED

The account’s credit wallet is exhausted for the period. Transports: mcp, rest, cli. Retryable: the same request can succeed later without a change. Do next: Top up or upgrade in the dashboard; the balance resets at the start of the next period.

QUOTA_SERVICE_UNAVAILABLE

The billing service could not debit; retry shortly. Transports: mcp, rest. Retryable: the same request can succeed later without a change. Do next: Retry in a few seconds. Nothing was debited.

RATE_LIMITED

Too many requests per minute; back off and retry. Transports: mcp, rest, cli. Retryable: the same request can succeed later without a change. Do next: Wait the seconds in retry_after, then send the request once more.

SECRET_ALREADY_ISSUED

This request already returned its one-time secret, which cannot be shown again. Transports: rest. Not retryable: change the request (or the credential) before calling again. Do next: Create a new key if you no longer have the original.

SHUTTING_DOWN

The server is draining; retry against the next revision. Transports: rest. Retryable: the same request can succeed later without a change. Do next: Retry; the next revision is already serving.

TIMEOUT

The request exceeded the CLI timeout. Transports: cli. Not retryable: change the request (or the credential) before calling again. Do next: Raise --timeout, or bound the call with limit so there is less to fetch.

TOKEN_NOT_FOUND

No listed token matches the name or ticker. Transports: mcp, rest. Not retryable: change the request (or the credential) before calling again. Do next: Check the spelling, or pass the contract address and chain.

TOOL_ERROR

The provider returned an error the receipt classifies; read runtime_status. Transports: mcp, rest, cli. Not retryable: change the request (or the credential) before calling again. Do next: Read runtime_status in the receipt; retry only when it says rate_limited or degraded.

TOOL_NOT_FOUND

No tool with that name; search_tools finds the right one. Transports: mcp, rest, cli. Not retryable: change the request (or the credential) before calling again. Do next: Call search_tools with the intent, then use the exact name it returns.

TOOL_REQUIRED

The request body is missing the tool field. Transports: rest. Not retryable: change the request (or the credential) before calling again. Do next: Put the tool name in the tool field of the request body.

TOOL_RETIRED

The tool was retired; the message names the replacement call. Transports: mcp, rest, cli. Not retryable: change the request (or the credential) before calling again. Do next: Call the replacement named in the message; the old name will not come back.

UNAUTHORIZED

The credential was rejected: revoked, expired, or malformed. Transports: rest, cli. Not retryable: change the request (or the credential) before calling again. Do next: Check the key in the dashboard, then send the current one; rotate it if it was revoked.

VALIDATION_ERROR

Arguments failed validation; the message names the field and accepted values. Transports: mcp, rest, cli. Not retryable: change the request (or the credential) before calling again. Do next: Fix the field named in the message; get_api_endpoint_schema gives its type and accepted values.