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
In the Node and Python SDKs, every non-2xx response throws a SociaHiveError whose .code field matches the table below.
Codes
| code | HTTP | When it fires | What to do |
|---|---|---|---|
auth_error | 401 | Missing, 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_found | 404 | The 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_input | 400 | Request 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_error | 422 | Input 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. |
conflict | 409 | Unique-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_conflict | 409 | A 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_error | 409 | The 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_error | 402 | Your 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_reached | 422 | A 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_required | 403 | The 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_owned | 400 | Turning 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_limit | 403 | Turning 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_selected | 400 | A 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_limit | 429 | You 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_error | 502 / 503 | A 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_error | 500 | Something 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.current | REST code | HTTP | When it fires | details.suggestion and what to do |
|---|---|---|---|---|
live_changed | live_changed | 409 | The 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_changed | pending_changed | 409 | The 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_changes | no_pending_changes | 404 | The flow has no unpublished changes to publish or discard. | Nothing to do. |
pending_changes | pending_changes_exist | 409 | An 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_format | 409 | A 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:
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 forauth_errorerr.isRateLimited— true forrate_limiterr.isNotFound— true fornot_founderr.isStateError— true forstate_errorandconflict
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
codebecause they never reached the application. - Platform-side errors that we surface untransformed — see
details.upstreamonupstream_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.