Developer
Error Reference
When something goes wrong, Social Neuron returns a structured error response with a clear message and actionable guidance. This page covers every error you may encounter and how to resolve it.
HTTP Error Codes
| Code | Meaning | How to Fix |
|---|---|---|
| 400 | Validation Error -- A required parameter is missing or has an invalid value. | Check the error message for which field failed. Verify parameter types match what the tool expects. |
| 401 | Authentication Failed -- Your API key is expired, invalid, or missing. | Re-authenticate with socialneuron-mcp login --device or generate a new API key from your dashboard. |
| 402 | Insufficient Credits -- Your account does not have enough credits for this operation. | Check your balance with sn credits. Purchase more credits or upgrade your plan. |
| 403 | Scope Not Allowed -- Your API key does not include the required scope for this operation. | Generate a new API key with the correct scopes. For example, publishing requires mcp:distribute. See the scope table for details. |
| 404 | Resource Not Found -- The requested item (post, plan, job) does not exist or belongs to another account. | Verify the ID with a list command first (e.g., sn posts or sn plan list). |
| 422 | Invalid Parameters -- The request was well-formed but contained semantic errors. | Review the specific validation message. Common causes: unsupported platform name, invalid date format, or caption exceeding platform limits. |
| 429 | Rate Limited -- Too many requests in a short period. | Wait until the time indicated in the X-RateLimit-Reset header, then retry. See Rate Limits below. |
| 500 | Server Error -- An unexpected error occurred on our side. | Retry once after a few seconds. If the error persists, check our status page or contact support. |
Application Error Messages
These messages appear in API and CLI responses when specific operations fail.
| Error Message | Cause | How to Fix |
|---|---|---|
| Access denied. Check your account permissions. | Your account or API key lacks permission for this resource. | Verify your subscription tier includes the feature you are trying to use. Starter plans have limited API access. |
| A duplicate record already exists. | You attempted to create something that already exists (e.g., duplicate post, duplicate brand profile). | Check for existing records before creating new ones. Use the --idempotency-key flag when publishing to prevent duplicates on retries. |
| Referenced record not found. | An operation referenced an ID (plan, account, preset) that does not exist. | Verify the referenced ID exists using a list command. |
| Content generation failed. Please try again. | The AI content generation service encountered an error. | Retry the request. If it fails repeatedly, try simplifying your prompt or reducing the content length. |
| AI service rate limit reached. Please wait and retry. | The underlying AI service is temporarily overloaded. | Wait 30-60 seconds and retry. Avoid sending multiple generation requests in parallel. |
| Content was blocked by the AI safety filter. Try rephrasing. | Your content or prompt triggered the AI safety filter. | Rephrase your request to avoid potentially sensitive content. Remove explicit or controversial language. |
| Media generation failed. Please try again. | Video or image generation encountered an error. | Retry the request. For video generation, ensure your input media URL is accessible and in a supported format. |
| Payment processing error. Please try again. | A billing or payment operation failed. | Verify your payment method is current in Settings > Billing. If the problem persists, contact support. |
| External service unavailable. Please try again. | A third-party service (social platform API, media processing) is temporarily down. | Wait a few minutes and retry. This is usually a transient issue. |
| Network request failed. Please try again. | A network connection to an external service timed out or was refused. | Check your internet connection. If using the CLI behind a proxy, ensure it is configured correctly. |
| Authentication expired. Please re-authenticate. | Your session or token has expired. | Run socialneuron-mcp login --device to get a fresh session. |
| Service temporarily unavailable. Please try again. | A backend service is undergoing maintenance or experiencing issues. | Wait a few minutes and retry. |
OAuth Errors
These errors occur when connecting or managing social platform accounts.
| Symptom | Cause | How to Fix |
|---|---|---|
| "Token expired" when posting | The OAuth token for a connected account has expired. | Run sn oauth-refresh --platforms <platform> or reconnect the account in Settings > Connected Accounts. |
| "Invalid grant" during login | The authorization code was used twice or has expired. | Start the login flow again from the beginning. |
| "Scope denied" after connecting | The social platform did not grant all requested permissions. | Disconnect and reconnect the account, making sure to approve all permission prompts. |
| Posts fail on one platform but not others | Platform-specific token or permission issue. | Run sn oauth-health to check token status per platform. Refresh or reconnect the affected platform. |
OAuth tokens can expire even when your Social Neuron session is active. Run sn oauth-health periodically to catch expiring tokens before they cause publishing failures.
Rate Limits
Rate limits vary by subscription tier:
| Plan | Requests per Minute |
|---|---|
| Starter | 30 |
| Pro | 60 |
| Team | 120 |
Every response includes rate limit headers:
| Header | Description |
|---|---|
X-RateLimit-Remaining | Requests remaining in the current window |
X-RateLimit-Reset | Unix timestamp when the limit resets |
Retry Strategies
Not all errors are retryable. Check the retryable field in JSON error responses before implementing automatic retries.
Recommended retry approach:
- Check credits first. Before starting an expensive operation (video generation, bulk publishing), call
sn creditsto verify you have sufficient balance. - Use exponential backoff for 429 and 500 errors. Start with a 2-second delay, doubling each retry up to a maximum of 30 seconds. Respect the
X-RateLimit-Resetheader when present. - Do not retry 400, 401, 402, or 403 errors. These require a configuration change (fix parameters, re-authenticate, upgrade plan, or change scopes) and will not succeed on retry.
- Use idempotency keys for publish operations. Pass
--idempotency-key <unique-key>to prevent duplicate posts when retrying after a timeout.
# Example: check balance before a video generation workflow BALANCE=$(socialneuron-mcp sn credits --json | jq '.data.balance') if [ "$BALANCE" -lt 50 ]; then echo "Not enough credits for video generation (need 50, have $BALANCE)" exit 1 fibash
Getting Help
If you encounter an error not listed here, or an error that persists after following the fix steps:
- Check the FAQ for common issues
- Review your account status at Settings > Billing
- Contact support at socialneuronteam@gmail.com with the full error message and your account email
Ready to try this? Sign up free and get 100 credits to start.