Skip to main content
Beyond HTTP status codes, Postsiva returns structured error fields in response bodies — especially for multi-platform operations and connection checks.

NOT_CONNECTED

Platform account is not linked to the workspace.
{
  "posts": [],
  "message": "LinkedIn not connected for this workspace.",
  "error": "NOT_CONNECTED",
  "source": null
}
PlatformMessage pattern
linkedinLinkedIn not connected for this workspace.
facebookFacebook not connected for this workspace.
instagramInstagram not connected for this workspace.
tiktokTikTok not connected for this workspace.
youtubeYouTube not connected for this workspace.
pinterestPinterest not connected for this workspace.
threadsThreads not connected for this workspace.
blueskyBluesky not connected for this workspace.
Where it appears:
  • GET /unified/posts — empty slice for disconnected platform
  • GET /unified/analytics — platform omitted from totals
  • Multi-platform post results[]success: false
Fix:
# Check status
curl "https://backend.postsiva.com/unified/oauth/token" \
  -H "X-API-Key: psk_live_YOUR_KEY"

# Connect
curl -X POST "https://backend.postsiva.com/unified/oauth/url" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: psk_live_YOUR_KEY" \
  -d '{"platform": ["linkedin"]}'
Bluesky requires handle + app_password — see Bluesky.

Plan blocked (plan_required)

Feature or credit not available on the workspace owner’s plan.
{
  "detail": {
    "error": "plan_required",
    "feature": "drafts_enabled",
    "plan": "free",
    "message": "Plan upgrade required for: drafts_enabled"
  }
}

Common feature gates

Feature keyBlocks
api_keys_enabledAPI key authentication
mcp_enabledUnified MCP access
gpt_app_enabledGPT Actions
drafts_enabledDraft create/list/publish
scheduling_enabledSchedule posts
analytics_enabledUnified analytics
ai_composer_enabledAI content/image generation
auto_replier_enabledAI comment replies
HTTP status: 403 Forbidden Credit exhaustion uses 402 Payment Required:
{
  "detail": "Insufficient posts credits"
}
Fix: Upgrade plan at postsiva.com or reduce usage.

Invalid API key

CodeMessageHTTP
APIKEY_INVALIDInvalid API key.401
APIKEY_NOT_FOUNDAPI key not found.401
APIKEY_REVOKEDAPI key has been revoked.401
APIKEY_EXPIREDAPI key has expired.401
APIKEY_RATE_LIMITAPI key rate limit exceeded.429 / 403
Fix:
  1. Confirm key starts with psk_live_
  2. Copy full key from Settings (shown once at creation)
  3. Revoke compromised keys and create new ones
MCP returns plain text in tool results:
Invalid or expired API key
That API key is invalid or revoked. Generate a new workspace API key...

Scope mismatch

API key scope restricts which platforms can be accessed.
{
  "detail": "This API key is not allowed for platform 'instagram'. Key scope: linkedin_only. Only platforms in the key's scope can be used."
}
HTTP status: 403 Forbidden

Scope examples

ScopeCan connect/post
linkedin_onlyLinkedIn only (default)
linkedin_postsRead-only: GET /unified/posts
linkedin,instagramLinkedIn + Instagram
fullAll supported platforms
Fix: Create a new key with appropriate scope in Settings → API Keys. OAuth connect, post, and read endpoints all enforce scope.

Platform-specific errors

ErrorPlatformCause
board_id_requiredPinterestMissing pinterest.board_id
bluesky_text_errorBlueskyPost creation failed
YouTube title messageYouTubeNo title provided
These appear in post results[] with success: false.

Handling in code

const res = await fetch("https://backend.postsiva.com/unified/post/text", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.POSTSIVA_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ platforms: ["linkedin"], default_text: "Hi" }),
});

if (res.status === 401) throw new Error("Check API key");
if (res.status === 403) {
  const err = await res.json();
  if (err.detail?.error === "plan_required") throw new Error("Upgrade plan");
  throw new Error("Scope or permission issue");
}

const data = await res.json();
for (const r of data.results ?? [data]) {
  if (!r.success && r.error === "NOT_CONNECTED") {
    console.warn(`${r.platform} not connected — skip or connect first`);
  }
}

HTTP errors

Status codes

Authentication

Scopes and plan table

Errors overview

Two-layer model