PostSider API Errors

The public API uses standard HTTP status codes plus the JSON Authorization header described in the API overview. Most errors return a body with a msg field; plan and validation errors carry more structured fields.

Status codes

Code	Meaning	Typical cause
`400`	Invalid request	Malformed body, a channel’s content failing validation, or an invalid `status` value
`401`	Missing or invalid credential	No `Authorization` header, an unknown key, an expired OAuth token, or no subscription row for the organization
`402`	Plan limit reached	Channel cap, monthly post quota, team seats, webhook count, or AI action limit exceeded; also returned when a plan does not include public API access
`403`	Forbidden	The caller’s role does not allow the operation; note that the API remaps `403` to `401` in some flows
`404`	Not found	Unknown post, channel, or endpoint
`409`	Conflict	Idempotency-Key replay mismatch
`413`	Payload too large	Upload exceeds the configured file-size limit
`429`	Rate limited	More than 60 requests per minute for the organization; honor `Retry-After`
`500`	Server error	Unexpected failure; retry, then check the logs

Plan-limit (402) bodies

Limit responses include the affected section so clients can map them to friendly messages:

{ "statusCode": 402, "message": "Plan limit reached", "section": "posts_per_month" }

sections: posts_per_month, channel, team_members, webhooks, ai. A missing public_api entitlement also returns 402 at the auth boundary.

Validation (400) bodies

Channel-level validation failures include which provider and channel failed:

{ "statusCode": 400, "provider": "x", "name": "My X", "message": "Content exceeds the 280 character limit" }

Idempotency (409)

Replaying an Idempotency-Key with a different body for the same organization returns 409. Replaying with the same key and body returns the original result.

Rate limits (429)

{ "msg": "Too many requests", "retryAfter": 30 }

Wait retryAfter seconds before retrying. See Rate limits for the window semantics.

SDK behavior

The @postsider/node SDK throws PostsiderApiError for every non-2xx response, with status, method, path, and the parsed response details.

Overview

MCP Server

REST API

SDK

PostSider API Errors

Status codes

Plan-limit (402) bodies

Validation (400) bodies

Idempotency (409)

Rate limits (429)

SDK behavior

​Status codes

​Plan-limit (402) bodies

​Validation (400) bodies

​Idempotency (409)

​Rate limits (429)

​SDK behavior

Status codes

Plan-limit (402) bodies

Validation (400) bodies

Idempotency (409)

Rate limits (429)

SDK behavior