Skip to main content

Frequently Asked Questions

Common questions about the Flow API and how to resolve issues.

Authentication​

Why am I getting a 401 Unauthorized error?​

Common causes:

  • Missing Authorization header
  • Incorrect header format (should be Bearer flow_sk_live_...)
  • Invalid or revoked API key
  • Using a test key (flow_sk_test_) in production

Solution:

# Correct format
curl https://api.flowsocial.app/v1/posts \
  -H "Authorization: Bearer flow_sk_live_abc12345_xyz789..."

Why am I getting a 403 Forbidden error?​

Common causes:

  • API key doesn't have permission for the requested resource
  • Trying to access another user's resources
  • Account suspended or restricted

Solution: Check your API key permissions in Settings → API Keys.

Rate Limits​

Why am I hitting rate limits?​

Common causes:

  • Making too many requests too quickly
  • Not implementing proper retry logic
  • Not using batch operations for bulk actions

Solution:

  1. Check X-RateLimit-Remaining header before each request
  2. Implement exponential backoff when you receive 429
  3. Use batch endpoints (/v1/posts/batch) for bulk operations
  4. Cache responses when possible

See Rate Limits for details.

How do I increase my rate limits?​

Upgrade your plan for higher limits. Enterprise customers can request custom limits by contacting support@flowsocial.app.

Posts​

Why is my post stuck in "queued" status?​

Common causes:

  • Scheduled time hasn't arrived yet
  • Connection tokens expired
  • Platform API issues

Solution:

  1. Check the scheduledFor timestamp
  2. Verify connections are still valid (POST /v1/connections/{id}/verify)
  3. Check status.flowsocial.app for platform issues

Why did my post fail?​

Common causes:

  • Content violates platform policies
  • Media format not supported
  • Connection tokens expired
  • Character limit exceeded

Solution: Use the preflight endpoint to validate before posting:

POST /v1/posts/preflight

What do the post statuses mean?​

StatusMeaning
queuedScheduled but not yet posted
flowingCurrently being posted to platforms
doneSuccessfully posted to all platforms
blockedFailed to post (check error details)

Connections​

Why did my OAuth connection fail?​

Common causes:

  • State mismatch (session expired)
  • Missing environment variables
  • Platform app not configured correctly
  • User denied permissions

Solution:

  1. Ensure your callback URL is correctly configured
  2. Check that all required scopes are requested
  3. Verify your platform app credentials

How do I refresh an expired connection?​

POST /v1/connections/{id}/refresh

If refresh fails, the user needs to re-authenticate through the OAuth flow.

Which platforms are supported?​

  • Twitter/X
  • LinkedIn (personal profiles and company pages)
  • Meta (Facebook and Instagram)
  • TikTok

Media​

What file types are supported?​

Images: JPEG, PNG, GIF, WebP Videos: MP4, MOV (platform-specific limits apply)

What are the file size limits?​

  • Images: 5MB per file
  • Videos: 100MB per file (varies by platform)

Why is my media upload failing?​

Common causes:

  • File too large
  • Unsupported format
  • File corrupted

Solution:

# Check file size before uploading
ls -la image.jpg

# Ensure correct content type
curl -X POST https://api.flowsocial.app/v1/media/upload \
  -H "Authorization: Bearer flow_sk_live_..." \
  -F "file=@image.jpg"

Webhooks​

Why aren't my webhooks being delivered?​

Common causes:

  • Webhook URL is unreachable
  • Webhook returns non-2xx status
  • Signature verification failing
  • Webhook is disabled

Solution:

  1. Check webhook is active: GET /v1/webhooks/{id}
  2. Check delivery history: GET /v1/webhooks/{id}/deliveries
  3. Test with: POST /v1/webhooks/{id}/test
  4. Ensure your endpoint returns 200 OK quickly

How do I verify webhook signatures?​

import crypto from 'crypto';

function verifySignature(payload: string, signature: string, secret: string): boolean {
  const [timestamp, sig] = signature.split(',').reduce((acc, part) => {
    const [key, value] = part.split('=');
    return { ...acc, [key]: value };
  }, {} as Record<string, string>);
  
  const expectedSig = crypto
    .createHmac('sha256', secret)
    .update(`${timestamp}.${payload}`)
    .digest('hex');
    
  return sig === `v1=${expectedSig}`;
}

See Webhooks for full documentation.

Pagination & Filtering​

Why am I getting different results than expected?​

Common causes:

  • Using perPage instead of per_page
  • Filter syntax incorrect
  • Sort order not specified

Solution:

# Correct pagination
GET /v1/posts?page=1&per_page=50

# Correct filtering
GET /v1/posts?filter[status]=queued&filter[channelId]=channel_123

# With sorting
GET /v1/posts?sort=-scheduledFor

See Advanced Querying for details.

SDKs​

Which SDKs are available?​

  • TypeScript/JavaScript: @flowdev/sdk
  • Python: flow-sdk
  • Go: github.com/flowdev/go-sdk

The SDK is throwing an error. What should I do?​

  1. Update to the latest SDK version
  2. Check your API key is valid
  3. Enable debug logging
  4. Check the API Status
// Enable debug mode in TypeScript SDK
const flow = new Flow('flow_sk_live_...', {
  debug: true,
});

General​

Where can I find my API key?​

  1. Log in to flow.flowsocial.app
  2. Go to Settings → API Keys
  3. Click "Create API Key"
  4. Copy and securely store the key (it's only shown once)

Is there a sandbox/test environment?​

Yes! Use test API keys (flow_sk_test_...) for development. Test keys have separate rate limits and don't affect production data.

How do I report a bug or request a feature?​

Still need help?​