SociaHive Docs

Error Reference

Every error code SociaHive returns, what it means, and how to recover.

Every non-2xx response from SociaHive carries a stable code string. The string is more reliable than the HTTP status for branching logic — statuses can shift between adjacent codes (e.g. 422 vs 400) as we tighten validation, but the code value is part of the public API.

Shape

{
  "error": "Human-readable message",
  "code": "rate_limit",
  "details": { "...": "optional context, schema varies per code" }
}

In the Node and Python SDKs, every non-2xx response throws a SociaHiveError whose .code field matches the table below.

Codes

codeHTTPWhen it firesWhat to do
auth_error401Missing, malformed, or invalid X-API-Key / OAuth bearer; key revoked; key lacks the required scope for this tool.Confirm key is set, has the right scope, and hasn't been rotated. SDKs expose this via err.isAuthError.
not_found404The requested resource (flow, post, account) doesn't exist OR is owned by a different user.Check the ID. Note: 404 is also returned when a resource exists but isn't accessible to your key (no information leak about other users' data).
invalid_input400Request body / query failed the input schema — wrong type, missing required field, bad format.The details object lists the failing fields. Fix the payload and retry.
validation_error422Input parsed but a business rule rejected it (e.g. scheduling a post in the past, applying a tag with reserved characters).Read details.reason for the specific rule violated. Not retriable without changing the input.
conflict409Unique-constraint collision — e.g. a webhook subscription with the same target_url already exists, or two flow nodes share an ID.Either update the existing resource or pick a different identifier.
keyword_conflict409A keyword you're trying to register on a flow trigger is already claimed by another active flow on the same account.Either deactivate the other flow, pick a different keyword, or scope to a specific post.
state_error409The resource is in a state that can't accept this operation. For a live flow's unpublished changes details.current says which: see Live flows with unpublished changes.Follow details.suggestion. While a flow is still being built it is wait_then_retry: get_flow reports build.status.
tier_error402Your subscription tier doesn't include this feature — e.g. randomizer nodes on the Free plan, or live-chat tools without Pro+.Upgrade the plan or remove the feature from the flow. details.required_tier tells you the minimum.
limit_reached422A counted resource has hit its tier cap — webhook subscriptions, connected accounts, scheduled posts per month, etc.Either delete an existing resource of the same kind or upgrade the plan.
human_auth_required403The request changes the account itself (/api/v1/account: delete, cancel deletion, deletion status) and came from an API key or a third-party app. Only you can do this, signed in to SociaHive or the SociaHive app.Do it in SociaHive or the SociaHive app. If you see this in the app, sign in again.
account_not_owned400Turning on a flow whose connected account isn't one of yours (for example after the account moved to another SociaHive account).Reconnect the account, or create the flow again on one of your connected accounts.
automated_account_limit403Turning on automation (activating a flow, or switching on AI Replies or AI Comments) for a connected account that isn't automated yet would go over your plan's automated-account limit (Free 0, Creator 1, Studio 4, Pro 10, Agency 100). Accounts that already run automation are not affected.Turn off automation on another account (unpublish its flows and switch off AI Replies / AI Comments) or upgrade the plan.
no_account_selected400A flow / analytics tool needs a specific connected account context but the agent didn't supply one (only happens via MCP).The chat-header account pill should auto-fill this; if it doesn't, pass account_id explicitly.
rate_limit429You exceeded the per-minute or daily quota.Honor Retry-After (seconds). The response details.window tells you which bucket tripped (read / write / expensive / daily). See Rate limits.
upstream_error502 / 503A platform we depend on (Instagram, Meta, OpenAI, etc.) returned an error or timed out.Usually transient — retry with exponential backoff. The details.upstream field names the platform.
unknown_error500Something we didn't anticipate.Retry once. If it persists, file an issue with the details.request_id value.

Live flows with unpublished changes

An edit to a live flow (published or paused) is saved as unpublished changes, and people keep getting the live version until the changes are published (publish_flow_changes, or POST /api/v1/flows/{id}/pending/publish). Over MCP a refusal is a state_error whose details.current names the case; over REST the response's code does.

MCP details.currentREST codeHTTPWhen it firesdetails.suggestion and what to do
live_changedlive_changed409The live version changed after the unpublished changes were made, so they can no longer be published.discard_then_redo: discard the changes and make them again.
pending_changedpending_changed409The unpublished changes were edited after the rev you sent was read.review_new_preview: read the changes again (the publish preview, or GET /api/v1/flows/{id}/pending) and send its new rev.
no_pending_changesno_pending_changes404The flow has no unpublished changes to publish or discard.Nothing to do.
pending_changespending_changes_exist409An edit or a turn-off of a flow that has unpublished changes, from a caller that cannot add to them: a REST client without the capability header, or deactivate_flow.publish_or_discard: publish or discard the changes first.
—legacy_format409A live flow stored in an older format, which can't be edited while it is on.Turn the flow off, edit it, then turn it on again.

A publish runs the same checks as turning a flow on; a failed check is a validation_error naming the step (field: "nodes.<id>"). When the version kept for undo can't be saved, nothing changes and the answer is a 503 with Retry-After: try again.

REST clients that send X-SociaHive-Client-Capabilities: pending-flow-versions write their edits to a live flow into the unpublished changes, as the MCP tools do. Without the header an edit to a live flow is checked against the draft rules, refused if it adds a problem that would block publishing, and otherwise applied live; it is also refused with pending_changes_exist while the flow has unpublished changes.

Special envelope: pending_confirmation

Destructive tools (delete_*, publish_post_now, disconnect_account) don't error on the first call — they return a confirmation envelope:

{
  "__mcp_envelope": "pending_confirmation",
  "confirmToken": "...",
  "summary": "Delete flow 'Welcome series' — 4 nodes, 1.2K executions",
  "affectedEntities": [{ "type": "flow", "id": "..." }]
}

Pass __confirmToken back on the second call within 5 minutes. See the Confirmation Flow section in the MCP setup guide.

SDK helpers

Convenience flags in the SDKs

Both Node and Python SDK error classes expose pre-computed flags for the codes you'll branch on most often:

  • err.isAuthError — true for auth_error
  • err.isRateLimited — true for rate_limit
  • err.isNotFound — true for not_found
  • err.isStateError — true for state_error and conflict

Use these instead of string-matching err.code when you can.

What's NOT in this list

  • HTTP-only failures (e.g. 502 from Cloudflare before the request hits us) — no code because they never reached the application.
  • Platform-side errors that we surface untransformed — see details.upstream on upstream_error.

If you hit a code that isn't in this table, file an issue with the response body — the table is the source of truth, but the codebase may have shipped a new code that hasn't propagated to docs yet.

On this page