Troubleshooting

401 Unauthorized - Invalid API Key

This error occurs when your API Key is missing, invalid, or expired.

Common Causes:

• • API Key not included in request headers
• • Typo in API Key value
• • API Key was revoked or regenerated
• • Using wrong header name

Solution:

# Verify your API Key
curl -X POST https://your-domain.com/api/agents/v1/auth/validate \
  -H "X-API-Key: your_api_key_here"

# If validation fails, generate a new API Key in Settings → API Keys

403 Forbidden - Insufficient Permissions

You don't have permission to perform this action.

Common Causes:

• • Account doesn't have required social media connections
• • API Key belongs to different account
• • Attempting to access another user's resources

Solution:

Ensure you have connected the required social media accounts in your SocialHub dashboard. Go to Settings → Connections and verify all platforms are properly authenticated.

Instagram Connection Not Found

The API cannot find an active Instagram connection for your account.

Solution:

1. 1. Log in to your SocialHub dashboard
2. 2. Go to Settings → Connections
3. 3. Click "Connect Instagram"
4. 4. Complete the OAuth authorization flow
5. 5. Verify the connection appears in your connections list
6. 6. Retry your API request

Facebook Page Not Selected

When publishing to Facebook, you must have a Facebook Page selected.

Solution:

1. 1. Go to Settings → Connections → Facebook
2. 2. Click "Select Page" and choose your Facebook Page
3. 3. Ensure the page appears as "Active" in your connections
4. 4. Retry your API request

400 Bad Request - Invalid Parameters

Your request contains invalid or missing required parameters.

Common Issues:

• Missing caption: The caption field is required

  { "caption": "Your post text here" }

• Empty platforms array: Must specify at least one platform

  { "platforms": ["instagram"] }

• Invalid date format: Use ISO 8601 format

  { "scheduled_for": "2024-12-25T10:00:00Z" }

413 Payload Too Large

Your request body exceeds the maximum allowed size.

Limits:

• • Maximum request body: 10 MB
• • Maximum media URLs per request: 10
• • Use the media preparation endpoint for large files

Solution:

Instead of sending media directly, use the /media/prepare endpoint to handle large files. See the Media Upload documentation.

429 Too Many Requests

You've exceeded the rate limit for this endpoint.

Rate Limits:

• • Authentication: 10 requests/minute
• • Publishing: 60 requests/hour
• • Media Preparation: 30 requests/hour
• • Scheduled Content: 100 requests/hour

Solution:

// Implement exponential backoff
async function retryWithBackoff(fn, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (error.response?.status === 429) {
        const retryAfter = error.response.headers['retry-after'];
        const delay = retryAfter ? parseInt(retryAfter) * 1000 : Math.pow(2, i) * 1000;
        await new Promise(resolve => setTimeout(resolve, delay));
      } else {
        throw error;
      }
    }
  }
  throw new Error('Max retries exceeded');
}

Media Preparation Timeout

Media preparation is taking longer than expected or timing out.

Common Causes:

• • Large file size (close to 500MB limit)
• • Slow download speed from source URL
• • Source URL requires authentication
• • Network connectivity issues

Solution:

• • Ensure media files are publicly accessible
• • Use faster hosting (CDN, S3, etc.)
• • Compress large files before uploading
• • Check status endpoint for detailed error messages