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 itsdoc_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 asAuthorization: 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: Follownext_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 againstGET /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 withreport_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 withhive_live_.
INVALID_ARGS
The CLI arguments are invalid. Transports: cli. Not retryable: change the request (or the credential) before calling again. Do next: Checkhive <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 withcontent-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 withlimit 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 withreport_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 inretry_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: Readruntime_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: Callsearch_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 thetool 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.
