Rate Limits

Per-minute and daily quotas for the SociaHive API and MCP server, plus the headers and back-off strategy.

SociaHive enforces per-user rate limits on every API key and OAuth token. Limits are bucketed by the kind of operation, not by the HTTP method — a tool that does a single read costs less budget than one that ships a generated flow graph.

The four buckets

Bucket	Limit	Window	Examples
read	120 requests	1 minute	`list_flows`, `get_flow`, `list_scheduled_posts`, `get_analytics_overview`, anything that fetches without mutating
write	30 requests	1 minute	`create_flow`, `update_node`, `add_edge`, `create_scheduled_post`, `cancel_scheduled_post`
expensive	5 requests	1 minute	`generate_flow` (AI flow generation), `search_published_media` (vector search), anything that fans out to an LLM or vector store
daily	1,000 requests	24 hours	A cap that applies across all buckets combined — protects against runaway loops

All limits are per user (per API key holder or OAuth subject), not per-key. Creating multiple keys doesn't multiply your quota.

Response when you exceed a bucket

HTTP/1.1 429 Too Many Requests
Retry-After: 23
Content-Type: application/json
 
{
  "error": "Rate limit exceeded for read bucket. Retry in 23s.",
  "code": "rate_limit",
  "details": {
    "window": "read",
    "limit": 120,
    "retry_after_seconds": 23
  }
}

The Retry-After header is canonical — honor it. details.window tells you which bucket tripped if you want to back off only that class of operation.

Recommended back-off

import { SociaHive, SociaHiveError } from '@sociahive/sdk'
 
async function withBackoff<T>(fn: () => Promise<T>, maxRetries = 3): Promise<T> {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await fn()
    } catch (err) {
      if (!(err instanceof SociaHiveError) || !err.isRateLimited || attempt === maxRetries - 1) {
        throw err
      }
      const wait = (err.retryAfter ?? Math.pow(2, attempt)) * 1000
      await new Promise(r => setTimeout(r, wait))
    }
  }
  throw new Error('unreachable')
}

Don't retry tighter than Retry-After says — you'll just bounce off the same bucket again and waste your daily-cap budget.

MCP-specific limits

Beyond the four buckets above, the MCP HTTP transport adds a concurrent-session cap of 200. A "session" is an open SSE connection; idle ones time out after 5 minutes. If you're spawning many short-lived MCP clients in parallel (e.g. CI jobs), close the session explicitly after each batch instead of relying on GC.

The daily cap is the floor you'll actually hit

For most consumers, the per-minute buckets are forgiving — 120 reads per minute is more than any interactive session uses. The daily 1,000-request cap is what bulk-import scripts and aggressive cron jobs hit first.

If you're doing bulk work, prefer the bulk endpoints (posts.bulk, bulk_update_flows) over loops of single calls — one bulk call counts as one request against your quota regardless of how many entities it touches.

What's NOT rate-limited

Authentication endpoints (/api/oauth/*) — separately throttled by Cloudflare at the edge
Public marketing pages and /api/v1/openapi.json (read-only static)
Outbound webhooks — feature in development, currently admin-only. The retry policy and signature scheme will be documented once the public surface stabilizes.

Tier-specific limits

The buckets above are the same for every paid tier. What changes by tier is the resource caps — connected accounts, scheduled posts per month, AI credits, etc. — not the API request rate. Tier resource caps are returned by the whoami MCP tool and the /api/v1/usage REST endpoint.