---
title: Error Reference
lastUpdated: '2026-06-03'
nextjs:
  metadata:
    title: Error Reference | Hive Intelligence
    description: Complete reference for Hive Intelligence API error codes, HTTP status codes, rate limit headers, and troubleshooting guidance.
    alternates:
      canonical: https://www.hiveintelligence.xyz/errors
    keywords: "hive api errors, crypto api error codes, mcp server errors, hive 401 429, mcp authentication errors, hive troubleshooting"
---


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

{% ai-doc-actions path="/errors" title="Error Reference" /%}

---

## REST API Error Format

Every REST error response returns this shape:

```json
{
  "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"
  }
}
```

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

```text
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) |

---

## Plan limits

Plan limits can change independently of the error envelope. Use this page for
error parsing and retry behavior; use [Rate Limits](/rate-limits),
[Pricing](/pricing), or [Dashboard Plans](/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:

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

1. **Retries with exponential backoff** - up to 3 attempts before giving up
2. **Returns 502** with `provider_error` type 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 `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:

```json
{
  "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:

```text
Authorization: Bearer YOUR_KEY
```

or (legacy alias)

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

Wait for the `Retry-After` period indicated in the response header, check usage
in the dashboard, and reduce request volume or review [Rate Limits](/rate-limits)
before increasing traffic.

### "TOOL_NOT_FOUND"

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

```bash
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:

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

---

## Related Pages

- [API Integration](/api-integration) - full integration reference for MCP and REST
- [Quick Start](/quick-start) - run your first Hive request
- [Dashboard Plans](/dashboard/plans) - view and upgrade your plan