Error Reference

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://www.hiveintelligence.xyz/errors#auth-required"
  }
}

HTTP status codes

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)

Plan limits

Plan limits can change independently of the error envelope. Use this page for error parsing and retry behavior; use Rate Limits, Pricing, or Dashboard Plans for the current per-minute and monthly credit limits.

Tool-level error codes

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

Provider error handling

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

1. Retries with exponential backoff: up to 3 attempts before giving up.
2. Returns 503 with error.type: "provider_error" and code PROVIDER_UNAVAILABLE if all retries fail.
3. Circuit breaker opens after 5 consecutive failures to the same provider, failing fast for 30 seconds before testing recovery.

A 503 PROVIDER_UNAVAILABLE 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. A handled provider error for a specific request returns 400 with code TOOL_ERROR.

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

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" or "QUOTA_EXCEEDED"

RATE_LIMITED (per-minute rate limit) responses include a Retry-After: 60 header. Wait that many seconds, then retry. QUOTA_EXCEEDED means your monthly credit balance is exhausted; it does not carry Retry-After. Credits refill when your billing cycle rolls over, or upgrade your plan. Check usage in the dashboard and review Rate Limits before increasing traffic.

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

Related pages

• API Integration - full integration reference for MCP and REST
• Quick Start - run your first Hive request
• Dashboard Plans - view and upgrade your plan