Rate limits - Hive Intelligence API limits and throttling

Hive enforces two limits: a per-minute request rate, applied per API key (so a single misbehaving agent or key does not starve other clients), and a monthly credit budget, tracked on your account wallet and shared across every key (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.

View MarkdownAsk Claude Ask ChatGPT

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 for full plan comparison and 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 refill on a rolling monthly cycle anchored to when your account wallet was created, not on the first of the calendar month. If a request exceeds your monthly credit budget, the response is 429 with error.code: "QUOTA_EXCEEDED" and X-Quota-Remaining: 0. A QUOTA_EXCEEDED response does not include a Retry-After header; credits return when your cycle rolls over, or upgrade your plan.

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 per-minute rate-limit throttles (RATE_LIMITED), the response includes a fixed Retry-After header:

text

Retry-After: 60

Wait the indicated 60 seconds before retrying. Retrying immediately will continue to return 429 until the window resets. (Monthly QUOTA_EXCEEDED responses do not carry Retry-After; see below.)

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 503 with code PROVIDER_UNAVAILABLE (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 503 PROVIDER_UNAVAILABLE` with provider error details, or `runtime_status: "rate_limited"`	Retry with backoff, narrow the query, use an alternate Hive tool, or check 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 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.

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 - compare plan quotas and upgrade
Contact - enterprise custom limits and production rollout review

Error Codes - RATE_LIMITED, QUOTA_EXCEEDED, and provider error handling
Response Formats - where retry metadata appears in REST and MCP results
Known Limitations - provider plan gates and response-size boundaries
API Integration - production request patterns and discovery caching