Skip to main content
Postsiva follows standard HTTP semantics. The response body is JSON with a detail field (FastAPI format) or structured error object.

​
Status code reference

CodeNameWhen it happens
400Bad RequestInvalid platform, missing required body field, unsupported post type
401UnauthorizedMissing, invalid, expired, or revoked API key
403ForbiddenPlan feature blocked, API key scope mismatch, workspace header mismatch
404Not FoundDraft, scheduled post, or resource ID does not exist
422Unprocessable EntityValidation failure — character limits, invalid enum, schema error
500Internal Server ErrorUnexpected server failure

​
400 Bad Request

Common causes:
ScenarioExample detail
Unknown platformInvalid or unsupported platform: 'twitter'. Supported: ...
Unsupported post typeThis platform does not support text posting.
Missing post_typepost_type is required
Empty platformsplatforms must have at least one platform
Invalid draft_platformsdraft_platforms must be a subset of platforms. Invalid: instagram.
Bluesky connect missing fieldshandle and app_password are required for bluesky
Fix: Validate platform slugs, post types, and required platform fields before calling. See Platforms overview.

​
401 Unauthorized

Common causes:
ScenarioResponse
No API key header401 — key required
Wrong key formatInvalid API key. (APIKEY_INVALID)
Revoked keyAPI key has been revoked. (APIKEY_REVOKED)
Expired keyAPI key has expired. (APIKEY_EXPIRED)
Fix: 
# Correct header
-H "X-API-Key: psk_live_YOUR_KEY"
Regenerate key in Settings → API Keys if compromised or revoked.

​
403 Forbidden

Three distinct 403 cases:

​
Plan feature blocked

{
  "detail": {
    "error": "plan_required",
    "feature": "scheduling_enabled",
    "plan": "free",
    "message": "Plan upgrade required for: scheduling_enabled"
  }
}
Feature gateRoutes affected
api_keys_enabledAPI key auth
mcp_enabledMCP server
drafts_enabled/unified/drafts, draft: true
scheduling_enabledscheduled_time, /unified/scheduled-posts
analytics_enabled/unified/analytics
Also 402 Payment Required for insufficient post or AI credits.

​
API key scope mismatch

{
  "detail": "This API key is not allowed for platform 'instagram'. Key scope: linkedin_only. Only platforms in the key's scope can be used."
}
Fix: Create a key with broader scope (e.g. linkedin,instagram or full).

​
Workspace mismatch

When using JWT + X-Workspace-Id, or when optional X-Workspace-Id with API key doesn’t match the key’s workspace: 
403 — workspace does not match API key
Fix: Omit X-Workspace-Id with API keys (workspace inferred from key).

​
404 Not Found

ResourceExample
DraftGET /unified/drafts/{id} — draft deleted or wrong ID
Scheduled postPATCH /unified/scheduled-posts/{id} — invalid ID
MediaReferenced media_id not in workspace
Fix: Verify IDs from list endpoints before update/delete.

​
422 Unprocessable Entity

Validation errors before the request reaches platform APIs.

​
Character limits

{
  "detail": "Max text character limit for bluesky is 300. Received 350 characters in default_text."
}
See Character limits.

​
YouTube title

{
  "detail": "Max text character limit for youtube is 100. Received 120 characters in youtube_title/default_text (video title)."
}

​
TikTok photo title

{
  "detail": "Max TikTok Business photo title length is 90 UTF-16 code units. Received 95 in tiktok_title."
}

​
Pydantic schema

Malformed JSON types, wrong field types — FastAPI returns field-level loc and msg arrays.

​
500 Internal Server Error

Unexpected failures — OAuth URL generation, storage upload, worker errors. Fix:
  • Retry with backoff
  • Check request payload for edge cases
  • Contact support if persistent
OAuth routes may trigger internal error notification emails for debugging.

​
Rate limiting

Heavy API key usage may return rate limit errors (implementation-specific status, often 429 or wrapped in 403 with APIKEY_RATE_LIMIT). Include retry-after logic in production integrations.

Postsiva errors

NOT_CONNECTED, plan codes

Authentication

Keys and scopes