Errors Overview

Postsiva uses standard HTTP status codes for request-level failures and structured error objects for platform-specific issues.

Two layers of errors

Layer	Where	Example
HTTP status	Response status line	`401`, `422`, `403`
Application error	Response body `error` field	`NOT_CONNECTED`, `plan_required`

Multi-platform posts often return HTTP 200 with mixed per-platform results — one platform succeeds while another fails.

HTTP status codes

See HTTP errors for full reference:

Code	Meaning
`400`	Bad request — invalid platform, missing required field
`401`	Missing or invalid API key
`403`	Forbidden — plan gate, scope mismatch, workspace mismatch
`404`	Resource not found
`422`	Validation — character limits, invalid body
`500`	Server error

Postsiva error codes

See Postsiva errors for application codes:

Code	Meaning
`NOT_CONNECTED`	Platform not linked to workspace
`plan_required`	Feature not on current plan
`APIKEY_INVALID`	Invalid or malformed API key
Scope restriction	Key not allowed for requested platform

Multi-platform response shape

{
  "results": [
    {
      "platform": "linkedin",
      "success": true,
      "post_id": "urn:li:share:123"
    },
    {
      "platform": "instagram",
      "success": false,
      "error": "NOT_CONNECTED",
      "message": "Instagram not connected for this workspace."
    }
  ]
}

Always iterate results and check success per platform.

MCP errors

MCP returns errors in-band as tool results (not separate HTTP auth endpoints):

Invalid or expired API key
Plan upgrade required for: mcp_enabled

Same underlying checks as REST.

Debugging checklist

401? — Verify X-API-Key header and key not revoked
403 plan? — Check plan feature (drafts, scheduling, MCP, API keys)
403 scope? — Key scope must include target platform
422? — Check character limits
NOT_CONNECTED? — Run GET /unified/oauth/token
Partial failure? — Inspect each item in results

HTTP errors

Status code reference

Postsiva errors

Application error codes

Authentication

Keys and scopes

Get started

Features

REST API

MCP

Platforms

Guides

Integrations

Errors

Reference

Two layers of errors

HTTP status codes

Postsiva error codes

Multi-platform response shape

MCP errors

Debugging checklist

HTTP errors

Postsiva errors

Authentication

​Two layers of errors

​HTTP status codes

​Postsiva error codes

​Multi-platform response shape

​MCP errors

​Debugging checklist

​Related

HTTP errors

Postsiva errors

Authentication

Two layers of errors

HTTP status codes

Postsiva error codes

Multi-platform response shape

MCP errors

Debugging checklist

Related