Socifyr MCP errors and fixes
When a Socifyr MCP tool fails, the result has isError: true and its text starts with Error: followed by the API message. This page lists the messages you are most likely to see and what to do about each. The wording comes from the API, so your client may show it slightly differently.
Why can't my MCP client connect to Socifyr?
These errors happen before any tool runs.
| Symptom or message | Cause | Fix |
|---|---|---|
Missing API key. Send an "Authorization: Bearer sk_..." header. (HTTP 401) | No header, or the value does not start with Bearer sk_ | Add the header in the client's connector settings. See MCP setup |
Invalid API key (HTTP 401) | The key was deleted, rotated or mistyped | Create a new key in the dashboard and update the client |
Method not allowed. Use POST for MCP requests. (HTTP 405) | The client sent GET or DELETE | Use a client that supports Streamable HTTP, or the local stdio server |
| HTTP 429 | More than 120 requests per minute from one IP | Wait a minute and retry |
Error: SOCIFYR_API_KEY environment variable is required (stderr, local server) | Env var missing | Set SOCIFYR_API_KEY in the client's env block |
Error: SOCIFYR_WORKSPACE_ID environment variable is required (stderr, local server) | Env var missing | Set SOCIFYR_WORKSPACE_ID |
| Tools do not appear in the client | Wrong field name for the URL, or the client was not restarted | Check the field for your client (url, serverUrl, httpUrl) and reload |
What do tool errors mean and how do I fix them?
| Message | Tool | Cause | Fix |
|---|---|---|---|
Connection "<slug>" not found or not active. Check your connections page for valid slugs. | posting and scheduling tools | The slug is wrong or the account is disconnected | Call list_connections and use a slug from it |
Media not found: <value> | post_image, post_video | The media ID does not exist in this workspace | Call list_media for valid IDs, or pass a public URL |
Upload limit reached for your plan. Upgrade to continue. | posting tools | Monthly post limit reached | Call get_usage; upgrade or wait for the monthly reset |
Scheduling is not available on your current plan. Upgrade to continue. | schedule_post, schedule_posts, and posting tools with scheduledAt | The free plan has no scheduling | Upgrade, or post now |
Storage limit reached for your plan. Delete unused media or upgrade to continue. | media uploads through the SDK, CLI or REST API | Library is full | Delete media or upgrade |
API key "<label>" reached its daily post limit (<n>/day). The limit resets at 00:00 UTC — ... | posting tools | A guardrail on the key | Wait for the UTC reset, or raise the limit in the dashboard |
X (Twitter) spend cap reached for API key "<label>" ... | posting tools to X | The key's monthly X spend cap | Wait for the monthly reset or ask an admin to raise the cap |
This API key has guardrails and cannot call this endpoint — use a dashboard session or an unrestricted key | refresh_connection, reconnect_connection, delete_media | Guarded keys are deny-by-default | Do this step in the dashboard, or use an unrestricted key |
This API key requires approval and cannot publish drafts directly — submit the post for approval and a teammate will review it | publish_draft | The key has requireApproval | Submit the draft for approval through the dashboard, SDK or REST API; a teammate approves it |
Nothing to update — provide at least one field (connections, text, scheduledAt, …). | update_post | Only postId was sent | Add at least one field to change |
Could not refresh "<slug>": ... | refresh_connection | The platform cannot refresh this token, or the refresh token is dead | Call reconnect_connection |
Only the workspace owner can connect accounts | reconnect_connection | The key's user is not the workspace owner | Ask the owner to run it or open the dashboard |
Connection not found | reconnect_connection | Unknown slug | Use a slug from list_connections |
Cannot retry an upload with status "<status>" (HTTP 409) | retry_post | The post is not failed or partial_failure | Use check_post_status to see its state |
Provide "rows" or a non-empty "csv". and A bulk schedule is limited to 500 rows. | schedule_posts | Empty or oversized batch | Send between 1 and 500 posts |
Error: No AI provider key set for this workspace. Add your own key in Settings → AI to use AI features. | generate_caption | The workspace has no AI key | Add one under Settings, AI. See AI composer and BYOK |
Per-row errors from schedule_posts such as scheduledAt must be in the future or text is required are reported in the result text as Row <n>: <message> and do not fail the whole call.
What if a post was accepted but failed on the platform?
The posting tool only confirms that the post was accepted. Call check_post_status with its ID. Each failed channel carries the platform's error text. Common fixes:
- Token expired or invalid: call
list_connections. If the account showsexpiring, callrefresh_connection. If it showsneeds reconnect, callreconnect_connectionand give the link to the account owner. Then callretry_post. - Platform rate limit: wait, then call
retry_post. - Media or format rejected: check the platform's rules on its platform page, change the media with
update_postif the post is still a draft or scheduled, or create a new post.
See error handling for the same failures across the SDK, CLI and REST API.
FAQ
Does the assistant see the real API error text?
Yes. The tool result includes the message from the API, which is why most errors above tell the model what to do next.
Why does reconnect_connection return a link instead of reconnecting?
Re-authorizing an account needs the owner to approve access on the platform's own page. The link is single use and expires after 10 minutes. See Connections and slugs.