Error codes and fixes
Errors share one JSON shape across the REST API. The SDKs, CLI and MCP server surface the same error text. Find your message below.
What does an error response look like?
json
{
"success": false,
"error": "Connection \"x-oldname\" not found or not active. Check your connections page for valid slugs.",
"statusCode": 400,
"path": "/api/content/text",
"timestamp": "2026-11-13T09:00:00.000Z"
}error is a string, or an array of strings for validation failures. Server errors (5xx) add a requestId, and every response carries an X-Request-Id header. The API rejects unknown body fields with 400.
What does each HTTP status mean?
| Status | Meaning | First thing to check |
|---|---|---|
| 400 | Validation failed or a business rule failed | Read error. |
| 401 | Missing or invalid API key | Authorization: Bearer sk_... header. |
| 403 | Permission, plan limit, guardrail or workspace access denied | The message says which. |
| 404 | Not found in this workspace | The ID or slug. |
| 409 | The resource is in the wrong state | Fetch it and read status. |
| 429 | Rate limit | Wait. See limits. |
| 5xx | Server error | Retry with backoff. Keep the requestId. |
Plan limits return 403, not 402.
Which errors are about my request?
| Message | Status | Fix |
|---|---|---|
text is required | 400 | Send a non-empty text on a text post. |
Connection "<ref>" not found or not active. Check your connections page for valid slugs. | 400 | List connections and copy an active slug. |
Media not found: <value> | 400 | The media ID is not in this workspace. |
All media must be of type "<type>" | 400 | Match media to the endpoint: photos, video or document. |
Platforms do not support <type>: <platforms> | 400 | Remove the listed accounts from this post. |
Provide "rows" or a non-empty "csv". | 400 | Send rows or a CSV with at least one data row. |
A bulk schedule is limited to 500 rows. | 400 | Split the batch. |
Scheduled time must be in the future | 400 | Use a later scheduledAt. |
Draft must have content type and at least one channel selected | 400 | Add connections to the draft. |
Draft must have content (text or media) before publishing | 400 | Add text or media. |
No failed channels to retry | 400 | Nothing to retry. |
Upload not found (status check) | 400 | Wrong ID. The status endpoint returns 400 here. |
Upload not found (other routes) | 404 | Wrong ID or another workspace. |
Which errors come from my plan?
| Message | Fix |
|---|---|
Upload limit reached for your plan. Upgrade to continue. | Wait for the monthly reset or upgrade. |
Storage limit reached for your plan. Delete unused media or upgrade to continue. | Delete media or upgrade. |
Scheduling is not available on your current plan. Upgrade to continue. | Upgrade, or post now. |
X (Twitter) post allowance reached (N/month on your plan). ... | Wait for the reset or upgrade. |
Webhooks are not available on your current plan. Upgrade to Business to continue. | Upgrade to Business. |
Numbers are in limits.
Which errors come from an API key's guardrails?
| Message | Fix |
|---|---|
API key "<label>" reached its daily post limit (<n>/day). The limit resets at 00:00 UTC ... | Wait, or raise dailyPostLimit. |
X (Twitter) spend cap reached for API key "<label>" ($<n>/month). ... | Wait for the monthly reset or raise the cap. |
This API key requires approval and cannot <action> — submit the post for approval and a teammate will review it | Submit for approval. |
This API key has guardrails and cannot call this endpoint — use a dashboard session or an unrestricted key | Use an unrestricted key for that route. |
This API key has guardrails and can only modify posts it created itself | Use another key or the dashboard. |
This API key has guardrails and can only edit drafts — this post is "<status>" | The post is past draft. |
This API key has guardrails and cannot manage API keys — change them from the dashboard | Use the dashboard. |
Content is not pending approval (409) | Already approved or rejected. |
Only a draft can be submitted for approval (409) | The post is not a draft. |
Which errors come from connections?
| Message or symptom | Fix |
|---|---|
reconnect_required: <slug> — <platform> rejected the saved credentials in a channel result | Refresh or reconnect, then retry. |
Connection not found (404) on refresh or reconnect | Use a slug from the connection list. |
Only the workspace owner can connect accounts (403) | Ask the owner. |
| Refresh returns 400 | The platform cannot refresh. Use a reconnect link. |
Workspace in the URL does not match the authorized workspace (X-Workspace-Id / API key) (403) | Use the key for that workspace. |
Which errors come from state conflicts?
| Message | Status | Fix |
|---|---|---|
Cannot retry an upload with status "<status>" | 409 | Only failed and partial_failure retry. |
Draft is already being published | 409 | Wait and check status. |
| Post not editable (publishing or published) | 409 | Only drafts and unpublished scheduled posts can change. |
| Upload is processing or publishing | 409 | Cannot delete mid-publish. Wait. |
Which errors come from AI?
| Message | Status | Fix |
|---|---|---|
No AI provider key set for this workspace. Add your own key in Settings → AI to use AI features. | 503 | Add a key. See AI guide. |
That API key could not be validated with the provider... | 400 | Check key, provider and model. |
How do SDK error classes map to these statuses?
| Status | TypeScript class |
|---|---|
| 400 | ValidationError |
| 401 | AuthenticationError |
| 403 | PermissionError |
| 404 | NotFoundError |
| 429 | RateLimitError (with retryAfter) |
| other | SocifyrError (408 timeout, 0 network_error) |
UsageLimitError maps to 402, which the API does not currently return for plan limits, so those arrive as PermissionError. Python raises AuthenticationError for a 403 because it has no PermissionError. See SDK errors and Python errors.
Which errors appear in a platform channel result?
Plain-language reasons the dashboard shows for failed channels:
| Error contains | Reason | Fix |
|---|---|---|
| rate limit, 429, daily limit | The platform's posting limit was reached. | Wait for the window, then retry. |
| expired, unauthorized, 401, token invalid | The connection needs reconnecting. | Reconnect, then retry. |
| permission, scope, 403, not approved | A required platform permission is missing. | Reconnect with all permissions. Some are pending platform review. |
| duplicate, already posted | The platform rejected a duplicate. | Change the content. |
| aspect ratio, resolution, duration | Media does not fit the format. | Re-encode the media. |
| too large, file size, 413 | File over the platform limit. | Compress. See platform constraints. |
| caption too long, character limit | Text over the limit. | Shorten it. |
| timeout, network, 5xx, temporarily | The platform did not respond. | Retry soon. |
Where are the surface-specific errors?
- MCP: MCP errors
- CLI: CLI reference
- Handling patterns: Error handling