All Hive API errors follow a consistent envelope so your code can parse failures programmatically.

REST API Error Format

Every REST error response returns this shape:

{
  "ok": false,
  "error": {
    "type": "authentication_error",
    "code": "AUTH_REQUIRED",
    "message": "API key required. Set Authorization: Bearer <key> (or x-api-key) header.",
    "request_id": "req_12345",
    "doc_url": "https://docs.hiveintelligence.xyz/errors#auth-required"
  }
}

Field	Description
`ok`	Always `false` on errors
`error.type`	Machine-readable error category
`error.code`	Specific error code for programmatic handling
`error.message`	Human-readable explanation
`error.request_id`	Unique ID for the request (include in support tickets)
`error.doc_url`	Link to the relevant documentation section

HTTP Status Codes

Status	Error Type	Code	When It Happens
400	`invalid_request_error`	`VALIDATION_ERROR`	Missing required parameter, invalid JSON
400	`invalid_request_error`	`MISSING_PARAM`	Required parameter not provided
401	`authentication_error`	`AUTH_REQUIRED`	No API key in request
403	`authentication_error`	`INVALID_API_KEY`	API key is invalid or revoked
404	`not_found_error`	`TOOL_NOT_FOUND`	Tool name doesn't exist in catalog
404	`not_found_error`	`ENDPOINT_NOT_FOUND`	URL path doesn't match any route
429	`rate_limit_error`	`RATE_LIMITED`	Too many requests in the current window
429	`rate_limit_error`	`QUOTA_EXCEEDED`	Monthly credit quota exhausted
500	`internal_error`	`INTERNAL_ERROR`	Server error
502	`provider_error`	`API_ERROR`	Upstream provider (CoinGecko, DeFiLlama, etc.) returned an error
503	`internal_error`	`SHUTTING_DOWN`	Server is restarting

Rate Limit Headers

All responses include rate limit headers:

RateLimit-Limit: 1000
RateLimit-Policy: 1000;w=60
X-RateLimit-Remaining: 999
X-Quota-Remaining: 499992
Retry-After: 60  (only on 429 responses)

Header	Description
`RateLimit-Limit`	Maximum requests allowed in the current window
`RateLimit-Policy`	Window size in seconds (`w=60` means per minute)
`X-RateLimit-Remaining`	Requests remaining before throttling
`X-Quota-Remaining`	Monthly credits remaining for the account, or `unlimited`
`Retry-After`	Seconds to wait before retrying (only present on `429` responses)

Rate Limits by Plan

Plan	Rate Limit	Monthly Credits
Demo (Free)	30 req/min	10,000
Analyst ($129/mo)	500 req/min	500,000
Pro ($499/mo)	1,000 req/min	2,000,000
Enterprise	3,000 req/min	Unlimited

Upgrade your plan from the Dashboard Plans page.

Tool-Level Error Codes

These codes appear in the error.code field when a tool execution fails:

Code	When It Happens
`INVALID_PARAMETER`	Parameter value is wrong type or out of range
`INVALID_COIN_ID`	Coin ID doesn't exist (e.g., typo in CoinGecko ID)
`INVALID_NETWORK_ID`	Network/chain ID not supported
`INVALID_ADDRESS`	Wallet or contract address is malformed
`COIN_NOT_FOUND`	CoinGecko can't find the requested coin
`POOL_NOT_FOUND`	DEX pool doesn't exist
`TOKEN_NOT_FOUND`	Token contract not found on the specified chain
`RATE_LIMIT`	Provider-level rate limit (separate from Hive rate limit)
`TIMEOUT`	Request to upstream provider timed out
`NETWORK_ERROR`	Connection to upstream provider failed

Provider Error Handling

When an upstream provider (CoinGecko, DeFiLlama, GoPlus, etc.) returns an error, Hive follows this sequence:

Retries with exponential backoff - up to 3 attempts before giving up
Returns 502 with provider_error type if all retries fail
Circuit breaker opens after 5 consecutive failures to the same provider, failing fast for 30 seconds before testing recovery

A 502 response with error.type: "provider_error" means the issue is upstream, not with your request. Retry after a short delay or check the provider's status page.

MCP Error Format

MCP errors follow the JSON-RPC 2.0 specification:

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32603,
    "message": "Internal server error"
  },
  "id": null
}

MCP Error Codes

Code	Meaning
`-32700`	Parse error - invalid JSON received
`-32600`	Invalid request - missing required JSON-RPC fields
`-32601`	Method not found - the method name doesn't exist
`-32603`	Internal error - server-side failure

Troubleshooting

"AUTH_REQUIRED" but I'm sending my key

Check that you're using the correct header format:

Authorization: Bearer YOUR_KEY

or (legacy alias)

x-api-key: YOUR_KEY

Common causes: sending the key as a query parameter instead of a header, or using Authorization: YOUR_KEY without the Bearer prefix.

"RATE_LIMITED" on the free tier

The Demo tier allows 30 requests per minute. Wait for the Retry-After period indicated in the response header, or upgrade to Analyst (500 req/min) from the Dashboard Plans page.

"TOOL_NOT_FOUND"

Tool names are case-sensitive. Use the REST discovery endpoint to find the correct name:

curl https://mcp.hiveintelligence.xyz/api/v1/tools?search=price \
  -H "Authorization: Bearer YOUR_KEY"

Or use the MCP resource hive://tools for the full live tool inventory.

Provider returning empty results

Some providers require specific parameter formats. Check hive://tools or the REST discovery endpoint for the exact schema:

curl https://mcp.hiveintelligence.xyz/api/v1/tools?search=TOOL_NAME \
  -H "Authorization: Bearer YOUR_KEY"

API Integration - full integration reference for MCP and REST
Quick Start - connect to Hive in minutes
Dashboard Plans - view and upgrade your plan