---
title: Rate Limits
lastUpdated: '2026-06-03'
nextjs:
  metadata:
    title: "Rate Limits - Hive Intelligence API Limits & Throttling"
    description: "Understand Hive API rate limits, throttling behavior, per-minute request ceilings, and monthly credit budgets across MCP, REST, and CLI."
    alternates:
      canonical: https://www.hiveintelligence.xyz/rate-limits
    keywords: "crypto api rate limits, mcp server limits, blockchain api throttling, hive api quota, hive credits"
---

Hive enforces two limits per account: a **per-minute request rate** (so a single misbehaving agent does not starve other clients) and a **monthly credit budget** (so each plan tier is bounded by usage). In the normal execution path, one tool call costs one credit regardless of upstream provider or payload size.

{% ai-doc-actions path="/rate-limits" title="Rate Limits" /%}

---

## Plan limits

| Plan | Requests/min | Monthly credits | API keys |
|------|--------------|-----------------|----------|
| Demo | 30 | 10,000 | 5 |
| Analyst | 500 | 500,000 | 10 |
| Pro | 1,000 | 2,000,000 | 25 |
| Enterprise | Custom | Custom | Custom |

Rate limits apply per API key. Credit budgets apply at the account level — creating multiple keys under one account does not multiply the credit pool. See [Pricing](/pricing) for full plan comparison and [Dashboard → Plans](/dashboard/plans) to upgrade.

---

## What counts as a credit

One MCP `tools/call` or one REST `POST /api/v1/execute` request costs one credit in the normal execution path. The credit cost is the same whether the upstream provider is CoinGecko, DeFiLlama, GoPlus, Alchemy, Codex, CCXT, Helius, Tenderly, or Moralis, and whether the response is small or large. Authenticated discovery requests such as `tools/list` and `GET /api/v1/tools` can also count against quota in the current backend, so production clients should cache discovery responses instead of polling the catalog on every user request.

Credits reset at the start of each calendar month. If a request exceeds your monthly credit budget, the response is `429` with `error.code: "QUOTA_EXCEEDED"` and `X-Quota-Remaining: 0`.

---

## Rate Limit Headers

Responses include headers showing your current quota state. IP-level throttles use standard `RateLimit-*` headers, while authenticated key-level limits include `X-RateLimit-*` and `X-Quota-Remaining`.

```text
RateLimit-Limit: 500
RateLimit-Policy: 500;w=60
X-RateLimit-Limit: 500
X-RateLimit-Remaining: 487
X-Quota-Remaining: 9992
```

| Header | Description |
|--------|-------------|
| `RateLimit-Limit` | Maximum IP-level requests allowed in the current window |
| `RateLimit-Policy` | Window policy, for example `500;w=60` |
| `RateLimit-Remaining` / `RateLimit-Reset` | Remaining requests and reset timing when provided by the limiter |
| `X-RateLimit-Limit` | Maximum authenticated API-key requests allowed in the current minute |
| `X-RateLimit-Remaining` | Authenticated API-key requests remaining before throttling |
| `X-Quota-Remaining` | Monthly credits remaining for the account, or `unlimited` |

---

## When You Hit the Limit

When you exceed your rate limit, Hive returns a `429 Too Many Requests` response:

```json
{
  "ok": false,
  "error": {
    "type": "rate_limit_error",
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. Maximum 500 requests per minute.",
    "doc_url": "https://www.hiveintelligence.xyz/errors#rate-limited"
  }
}
```

On hard throttles, the `Retry-After` header contains the wait time in seconds:

```text
Retry-After: 42
```

Wait for the indicated period before retrying. Retrying immediately will continue to return `429` until the window resets.

---

## Upstream provider limits

Hive normalizes billing and request shape, but upstream providers still have their own quotas, plan gates, endpoint limits, and temporary throttles. Those limits vary by provider, credential tier, endpoint, and provider-side status, so do not build production logic around static provider-limit numbers from a docs page.

If your Hive key is over its plan rate, Hive returns `HTTP 429`. If an upstream provider limit or provider outage is hit, the response generally surfaces as `HTTP 502` with a provider error payload or a `rate_limited` runtime status rather than a Hive quota error.

| Situation | Typical signal | What to do |
| --- | --- | --- |
| Hive plan rate exceeded | `HTTP 429`, `Retry-After`, `RATE_LIMITED` | Wait for the retry window, reduce concurrency, cache, batch, or upgrade. |
| Hive monthly credit budget exhausted | `HTTP 429`, `QUOTA_EXCEEDED`, `X-Quota-Remaining: 0` | Stop nonessential calls, wait for monthly reset, or upgrade. |
| Upstream provider throttled or unavailable | `HTTP 502` with provider error details, retryable error code, or `runtime_status: "rate_limited"` | Retry with backoff, narrow the query, use an alternate Hive tool, or check [Known Limitations](/known-limitations). |
| Upstream provider plan gate | Provider error, empty/partial payload, or feature-specific warning | Inspect `hive://providers`, the live tool schema, and the provider error before assuming the tool is unavailable globally. |

Hive retries provider failures where safe before surfacing an error to you. See [Error Codes](/errors) for provider error handling details.

---

## Best Practices

**Cache responses where possible.** Token prices and protocol TVL don't change every second. A short TTL cache reduces your request count significantly.

**Use category endpoints for focused queries.** Category-scoped endpoints (`/hive_market_data/mcp`, `/hive_security_risk/mcp`) expose a smaller tool surface and reduce the chance of hitting provider limits unrelated to your task.

**Batch with multi-asset tools.** Tools like `get_price` accept comma-separated IDs (`"ids": "bitcoin,ethereum,solana"`). One request returns data for multiple assets instead of one request per asset.

---

## Need Higher Limits

- [Pricing](/pricing) - compare plan quotas and upgrade
- [Contact](/contact) - enterprise custom limits and production rollout review

---

## Related

- [Error Codes](/errors) - `RATE_LIMITED`, `QUOTA_EXCEEDED`, and provider error handling
- [Response Formats](/response-formats) - where retry metadata appears in REST and MCP results
- [Known Limitations](/known-limitations) - provider plan gates and response-size boundaries
- [API Integration](/api-integration) - production request patterns and discovery caching