> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hiveintelligence.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> What Hive's errors mean and what to do about each one.

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

| Error | Cause | Fix |
| - | - | - |
| Missing credential | A protected surface was called with no auth | Connect via OAuth, or send a bearer key |
| Invalid key | The key is wrong, disabled, or revoked | Check it in the dashboard; create a new one if disabled |
| Expired session | An OAuth credential lapsed | Reconnect the client |

<Note>
  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.
</Note>

## Quota and rate

| Error | Cause | Fix |
| - | - | - |
| Anonymous cap reached | 25 material calls used for this IP today | Sign in, or wait for 00:00 UTC |
| Credits exhausted | Monthly allowance spent | Upgrade, or wait for the cycle to reset |
| Rate limited | Too many requests this minute | Back off and retry; do not retry immediately |

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

## Tools and arguments

| Error | Cause | Fix |
| - | - | - |
| Unknown tool (`TOOL_NOT_FOUND`, REST 404) | The name does not exist in the deployed catalog | Run `search_tools` with your task and retry with the exact name; the receipt's `next_action` says the same |
| Retired tool (`TOOL_RETIRED`, REST 410) | The name was removed in a release (for example the Codex-era tools retired on 2026-09-06) | Call the replacement named in the message with its own argument names. Never retry the retired name; it will not come back |
| Invalid arguments (`VALIDATION_ERROR`, REST 422) | Wrong shape, type, or a missing required field | Call `get_api_endpoint_schema` and rebuild the call. The hero tools also accept common aliases such as `token_address`, `contract_address`, `wallet`, and `network` |
| Unsupported chain | The tool does not cover that chain | Check the category page for coverage |

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

| Error | Cause | Fix |
| - | - | - |
| Provider unavailable | The upstream source is down or not configured | Retry later; check `runtime_status` |
| Provider degraded | The source timed out or returned a 5xx, so it is unstable right now | Retry after a pause; treat any partial result as low confidence |
| Upstream timeout | The provider did not respond in time | Retry once, then fall back |

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.

### ALERT\_NOT\_FOUND

No alert with that id belongs to this account. Transports: mcp, rest. Not retryable: change the request (or the credential) before calling again.

**Do next:** List alerts with `hive_list_alerts` and use an id from that account.

### ANON\_AUTH\_REQUIRED

This tool is not on the keyless lane; add a key or sign in. Transports: mcp, rest, cli. Not retryable: change the request (or the credential) before calling again.

**Do next:** Sign in or add an API key; every read-only tool still works keyless.

### ANON\_GLOBAL\_CAP\_EXCEEDED

Hive's shared keyless allowance for today is spent; a key is not subject to it. Transports: mcp, rest, cli. Retryable: the same request can succeed later without a change.

**Do next:** Add an API key; the shared keyless pool does not apply to keyed callers.

### ANON\_QUOTA\_EXCEEDED

The keyless daily allowance for this IP is spent; resets 00:00 UTC. Transports: mcp, rest, cli. Retryable: the same request can succeed later without a change.

**Do next:** Wait for the 00:00 UTC reset, or add an API key to leave the keyless lane.

### ANON\_QUOTA\_UNAVAILABLE

The keyless limiter is unreachable; retry in a few seconds or use a key. Transports: mcp, rest. Retryable: the same request can succeed later without a change.

**Do next:** Retry in a few seconds, or add an API key to skip the keyless limiter.

### 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; keyless discovery still works. 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. Read-only tools work without one.

### 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.

### 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`.

### MEMORY\_FACT\_NOT\_FOUND

No memory fact with that id belongs to this account. Transports: mcp, rest. Not retryable: change the request (or the credential) before calling again.

**Do next:** List facts with `hive_list_memory_facts` and use an id from that account.

### 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.

### MONITOR\_CREDIT\_EXHAUSTED

Scheduled monitors paused: the account's credits are exhausted. Transports: mcp, rest. Retryable: the same request can succeed later without a change.

**Do next:** Top up in the dashboard; paused monitors resume on the next cycle.

### MONITOR\_CREDIT\_UNAVAILABLE

The monitor billing check is unavailable; runs retry next cycle. Transports: mcp, rest. Retryable: the same request can succeed later without a change.

**Do next:** Nothing to do; the next scheduled run retries the billing check.

### MONITOR\_NOT\_FOUND

No monitor with that id belongs to this account. Transports: mcp, rest. Not retryable: change the request (or the credential) before calling again.

**Do next:** List monitors with `hive_list_monitors` and use an id from that account.

### 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

The signing secret was already issued for this subject; rotate it instead. Transports: rest. Not retryable: change the request (or the credential) before calling again.

**Do next:** Rotate the existing secret instead of issuing a second one.

### 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.

### STATE\_BACKEND\_UNAVAILABLE

Hive's state store is unreachable; retry shortly. Transports: mcp, rest. Retryable: the same request can succeed later without a change.

**Do next:** Retry in a few seconds; no state was changed.

### STATE\_SUBJECT\_ARCHIVE\_FORBIDDEN

This credential may not archive that subject. Transports: mcp, rest. Not retryable: change the request (or the credential) before calling again.

**Do next:** Use the credential that owns the subject.

### STATE\_SUBJECT\_ARCHIVED

The subject this call is scoped to was archived. Transports: mcp, rest. Not retryable: change the request (or the credential) before calling again.

**Do next:** Use a live subject; archived subjects are readable but not writable.

### STATE\_SUBJECT\_NOT\_FOUND

The subject this call is scoped to does not exist. Transports: mcp, rest. Not retryable: change the request (or the credential) before calling again.

**Do next:** Create the subject first, or call with a subject id this credential owns.

### 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.

### 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.

### VERIFICATION\_FAILED

The task result failed validate\_task\_result; the message names the failing check. Transports: mcp. Not retryable: change the request (or the credential) before calling again.

**Do next:** Fix the check named in the message, then call `validate_task_result` again.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.