Errors & rate limits

HTTP status codes and quotas.

HTTP status

Status	Meaning
`400`	Bad request / validation
`401`	Missing or invalid credential
`403`	Forbidden (e.g. trial expired, wrong org resource)
`404`	Not found
`429`	Rate limited
`5xx`	Server error — retry with backoff

Rate limits (Public API + MCP)

Limits are per organization and shared across Public API and MCP so clients cannot double the quota by using both.

Action	Limit	Applies to
Create post	100 / hour	`POST /posts`, MCP `socioi_create_post`
GET / read	600 / minute	All Public API GETs (incl. TikTok creator-info / analytics), MCP read tools
Media upload-url	60 / minute	`POST /media/upload-url`
Upload from URL	30 / minute	`POST /media/upload-from-url`, MCP `socioi_upload_media_from_url`

429 responses include a Retry-After header and JSON retryAfter (seconds). Production uses Redis (REDIS_URL) so limits survive restarts and multi-instance deploys.

Plans also enforce channel quotas. Check GET /channels/quota.

Common validation errors

Status	Message (example)	Fix
`403`	One or more channels are invalid	Use channel ids from `GET /channels` that you can access
`403`	One or more media items are invalid	Use media ids from your own workspace (`GET /media`)
`400`	YouTube title must be 100 characters or fewer	Shorten `title`; `<` and `>` are not allowed either
`400`	YouTube madeForKids must be true or false	Send a boolean
`400`	TikTok postMode must be direct or inbox	Use `direct` or `inbox`
`400`	TikTok branded content (brandContent) cannot use privacyLevel SELF_ONLY	Choose another visibility or drop `brandContent`
`400`	settings.__type "…" does not match channel provider "…"	Match `__type` to the channel's provider

Publishing errors from the networks themselves (expired access, unsupported media, TikTok visibility no longer allowed) appear on the post target's errorMessage, not as an HTTP error on create.

Trial expired

JSON

{ "error": "TRIAL_EXPIRED", "message": "…", "trialEndsAt": "…" }

Upgrade on https://socioi.com/billing.