# 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](/docs/developer-api#scopes) 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](#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](https://socialneuron.com) 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 on the **Integrations** page. |
| "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. |

:::warning
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 endpoint category:

| Category | Limit |
|----------|-------|
| Text generation | 30 requests/min |
| Image generation | 10 requests/min |
| Video generation | 5 requests/min |
| Analytics queries | 60 requests/min |
| All other endpoints | 60 requests/min |

Additionally, a global IP-based limit of 60 requests/min applies.

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

:::tip
Not all errors are retryable. Check the `retryable` field in JSON error responses before implementing automatic retries.
:::

**Recommended retry approach:**

1. **Check credits first.** Before starting an expensive operation (video generation, bulk publishing), call `sn credits` to verify you have sufficient balance.
2. **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-Reset` header when present.
3. **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.
4. **Use idempotency keys for publish operations.** Pass `--idempotency-key <unique-key>` to prevent duplicate posts when retrying after a timeout.

```bash
# 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
fi
```

## Getting Help

If you encounter an error not listed here, or an error that persists after following the fix steps:

1. Check the [FAQ](/docs/faq) for common issues
2. Review your account status at **Settings > Billing**
3. Contact support at socialneuronteam@gmail.com with the full error message and your account email

---

Ready to try this? [Sign up free](https://socialneuron.com) and get 50 free credits to start.