social-media-api-best-practices

name	social-media-api-best-practices
description	Best practices for integrating social media APIs (Instagram, TikTok, YouTube, Twitter/X, LinkedIn, Facebook, Threads, Pinterest, Bluesky, Snapchat, Google Business, Reddit, Telegram). Covers OAuth, AT Protocol, rate limiting, media uploads, encryption, and error handling. Use when building social media integrations, scheduling systems, or debugging platform API issues.

Social Media API Best Practices

Battle-tested patterns from scheduling 1M+ posts across 13 platforms.

---

1. Authentication Patterns

OAuth 2.0 Platforms

Instagram (Meta Graph API)

• Two-step token exchange: short-lived (1 hour) → long-lived (60 days)
• Use auth_type: 'rerequest' to force permission re-prompts
• Exchange endpoint: ig_exchange_token grant type
• Scopes: instagram_business_basic, instagram_business_content_publish, instagram_business_manage_messages, instagram_business_manage_comments, instagram_business_manage_insights

Twitter/X (PKCE Required)

• PKCE with S256 code challenge is mandatory
• Embed code verifier in state: ${state}-cv_${codeVerifier}
• Scopes: tweet.read, tweet.write, users.read, offline.access, media.write, dm.read, dm.write
• Access token: 2 hours, refresh token: long-lived

function generateCodeVerifier(): string {
  return crypto.randomBytes(32).toString('base64url');
}

function generateCodeChallenge(verifier: string): string {
  return crypto.createHash('sha256').update(verifier).digest('base64url');
}

function extractCodeVerifierFromState(state: string): string {
  const match = state.match(/-cv_(.+)$/);
  return match ? match[1] : '';
}

TikTok

• Full UX compliance required for API audit approval
• Must show: privacy_level selector, comment/duet/stitch toggles
• Commercial content disclosure mandatory
• Scopes: user.info.basic, user.info.profile, user.info.stats, video.publish, video.upload, video.list

LinkedIn

• Always include header: X-RestLi-Protocol-Version: 2.0.0
• API version header: LinkedIn-Version: 202511 (some endpoints use 202505 or 202401)
• Access token: 60 days, refresh token: 365 days
• Supports both personal (urn:li:person:) and organization (urn:li:organization:) posts
• Personal scopes: openid, profile, r_basicprofile, email, w_member_social, w_member_social_feed, r_member_postAnalytics, r_member_profileAnalytics, r_1st_connections_size
• Organization scopes: w_organization_social, w_organization_social_feed, r_organization_admin, r_organization_social, r_organization_social_feed, r_organization_followers

YouTube

• Requires access_type=offline AND prompt=consent for refresh tokens
• Supports both user channels and brand accounts
• Scopes: youtube.upload, youtube, youtube.force-ssl, yt-analytics.readonly

Facebook

• Page access tokens are separate from user tokens
• Exchange user token for page token via /me/accounts
• Supports scheduled publishing via scheduled_publish_time
• Scopes: pages_manage_posts, pages_show_list, pages_read_engagement, pages_manage_engagement, pages_read_user_content, business_management, pages_messaging

Threads

• Similar to Instagram (Meta), 2-step token exchange
• Use th_exchange_token grant type
• Scopes: threads_basic, threads_content_publish, threads_manage_replies, threads_read_replies, threads_manage_insights, threads_delete

Pinterest

• OAuth 2.0 with refresh tokens
• Scopes: pins:read, pins:write, boards:read, boards:write, user_accounts:read

Google Business Profile

• Google OAuth with scopes: business.manage, userinfo.profile, userinfo.email
• Uses My Business v4 API

Reddit

• OAuth with duration=permanent for long-lived tokens
• Strict user-agent requirement - Reddit enforces descriptive user agents
• Scopes: identity, submit, read, mysubreddits, privatemessages, history, edit, vote

const headers = {
  'User-Agent': 'YourApp/1.0 by /u/YourUsername'
};

Non-OAuth Platforms

Bluesky (AT Protocol)

• No traditional OAuth - uses DIDs (Decentralized Identifiers)
• Authentication via accessJwt + refreshJwt from AT Protocol
• PDS (Personal Data Server) resolution required
• Auto-refresh on ExpiredToken error

// Bluesky authentication
const session = await agent.login({
  identifier: 'user.bsky.social',
  password: 'app-password'
});
// session contains: accessJwt, refreshJwt, did, handle

Snapchat

• Basic auth, allowlist-only (requires Snapchat dev team approval)
• Limited public API - profile API focus
• Scopes: snapchat-profile-api

Telegram

• Bot token only - no OAuth flow
• Token format: BOT_ID:SECRET
• No user authentication, bot must be added to chat/channel

---

2. Rate Limiting Strategies

Platform-Specific Limits

Platform	Key Limit	Strategy
Instagram	100 posts/day per account	Queue and spread
TikTok	5 pending uploads/24h	Wait for processing
Twitter	3-tier limits (app + user + endpoint)	Check all three
LinkedIn	Generous general, strict bulk	Batch carefully
YouTube	Daily upload quota per channel	Monitor quota
Reddit	60 requests/minute	Respect headers
Threads	Aggressive rate limiting	Fails fast

Twitter's Three-Tier Rate Limits

Twitter has THREE levels of limits - check all:

1. App-level 24-hour limit (most restrictive)
2. User-level 24-hour limit
3. Endpoint-specific rate limit

function parseRateLimitHeaders(headers: Headers) {
  return {
    // Endpoint limits
    remaining: parseInt(headers.get('x-rate-limit-remaining') || '0'),
    reset: parseInt(headers.get('x-rate-limit-reset') || '0'),
    // App-level 24h limits
    appRemaining: parseInt(headers.get('x-app-limit-24hour-remaining') || '0'),
    appReset: parseInt(headers.get('x-app-limit-24hour-reset') || '0'),
    // User-level 24h limits
    userRemaining: parseInt(headers.get('x-user-limit-24hour-remaining') || '0'),
    userReset: parseInt(headers.get('x-user-limit-24hour-reset') || '0'),
  };
}

Exponential Backoff Pattern

async function withRetry<T>(
  fn: () => Promise<T>,
  maxRetries = 3,
  baseDelay = 5000
): Promise<T> {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    try {
      return await fn();
    } catch (error) {
      if (!isRetryableError(error) || attempt === maxRetries) throw error;
      const delay = Math.min(baseDelay * Math.pow(2, attempt), 30000);
      await sleep(delay);
    }
  }
  throw new Error('Max retries exceeded');
}

function isRetryableError(error: any): boolean {
  const status = error.status || error.statusCode;
  return [429, 500, 502, 503].includes(status);
}

---

3. Media Requirements

Complete Platform Limits

Platform	Max Image	Max Video	Aspect Ratio	Special
Instagram	8MB	100MB stories, 300MB reels	4:5 to 1.91:1 feed, 9:16 stories	10 carousel items
TikTok	20MB	4GB, 3s-10min	9:16 strict	35 photo carousel
Twitter	5MB	512MB, 2min 20s	Flexible	1-4 images
LinkedIn	8MB	5GB	Flexible	20 image carousel
YouTube	2MB thumbnail	256GB	16:9 preferred	Resumable upload
Facebook	10MB	4GB	Flexible	10 multi-image
Threads	8MB	1GB, 5min	9:16 vertical	10 carousel
Pinterest	32MB	2GB	Flexible	Requires cover image
Bluesky	1MB	50MB, 3min	Flexible	AT Protocol
Snapchat	20MB	500MB	9:16	AES encryption
Google Business	5MB	N/A	Flexible	Images only
Reddit	20MB	N/A	Flexible	Via URL
Telegram	10MB	50MB	Flexible	4096 char limit

Golden Rule: Stream Large Files

Never load entire files into memory:

// BAD - loads entire file into memory
const buffer = await fetch(url).then(r => r.arrayBuffer());

// GOOD - streams directly
const response = await fetch(url);
await uploadToPlatform(response.body); // Pass the stream

Problematic Media Sources

These hosts return HTML or timeout instead of direct media:

const PROBLEMATIC_HOSTS = [
  'drive.google.com',
  'docs.google.com',
  'dropbox.com',
  'onedrive.live.com',
  '1drv.ms'
];

// Solution: Re-host to your own storage first
if (PROBLEMATIC_HOSTS.some(h => url.includes(h))) {
  url = await reHostToStorage(url);
}

Dropbox URL Fix

function fixDropboxUrl(url: string): string {
  if (url.includes('dropbox.com') && url.includes('dl=0')) {
    return url.replace('dl=0', 'dl=1');
  }
  return url;
}

---

4. Video Upload Patterns

Chunked Upload (Twitter)

async function chunkedUpload(videoBuffer: Buffer, mediaType: string) {
  const CHUNK_SIZE = 4 * 1024 * 1024; // 4MB chunks

  // INIT
  const initRes = await api.post('/media/upload', {
    command: 'INIT',
    total_bytes: videoBuffer.length,
    media_type: mediaType
  });
  const mediaId = initRes.media_id_string;

  // APPEND chunks
  for (let i = 0; i < Math.ceil(videoBuffer.length / CHUNK_SIZE); i++) {
    const chunk = videoBuffer.slice(i * CHUNK_SIZE, (i + 1) * CHUNK_SIZE);
    await api.post('/media/upload', {
      command: 'APPEND',
      media_id: mediaId,
      media: chunk.toString('base64'),
      segment_index: i
    });
  }

  // FINALIZE
  await api.post('/media/upload', {
    command: 'FINALIZE',
    media_id: mediaId
  });

  // Poll for processing
  await pollProcessingStatus(mediaId);

  return mediaId;
}

Resumable Upload (YouTube)

YouTube supports resumable uploads for reliability with large files. Use the youtube-chunked-upload module or implement the resumable upload protocol.

Processing Status Polling

async function pollProcessingStatus(mediaId: string, maxWaitMs = 300000) {
  const startTime = Date.now();

  while (Date.now() - startTime < maxWaitMs) {
    const status = await api.get(`/media/upload?command=STATUS&media_id=${mediaId}`);

    if (status.processing_info?.state === 'succeeded') return;
    if (status.processing_info?.state === 'failed') {
      throw new Error(status.processing_info.error?.message || 'Processing failed');
    }

    const checkAfter = (status.processing_info?.check_after_secs || 5) * 1000;
    await sleep(checkAfter);
  }

  throw new Error('Processing timeout');
}

---

5. Error Handling

Error Categorization

type ErrorType = 'refresh-token' | 'retry' | 'user-error';

function categorizeError(platform: string, error: any): ErrorType {
  if (isTokenError(error)) return 'refresh-token';
  if (isTemporaryError(error)) return 'retry';
  return 'user-error';
}

Instagram Error Codes

Code	Meaning	Action
2207001	Spam detected	User error
2207003	Media download timeout	Retry
2207004	Image too large (>8MB)	Compress
2207006	Media not found	User error
2207026	Unsupported video format	Re-encode
2207042	100 posts/day exceeded	Wait 24h
2207050	User restricted	User error
2207051	Blocked (but may have posted!)	Verify
2207052	Media fetch failed	Use direct URLs

The Instagram 2207051 Edge Case

Instagram's anti-spam sometimes returns "blocked" but actually publishes:

async function handleInstagram2207051(accountId: string) {
  await sleep(5000);

  const recentMedia = await getRecentMedia(accountId);
  const justPosted = recentMedia.find(m =>
    Date.now() - new Date(m.timestamp).getTime() < 60000
  );

  if (justPosted) {
    return { success: true, postId: justPosted.id };
  }
  throw new Error('Post actually failed');
}

TikTok Error Codes

Code	Meaning	Action
access_token_invalid	Token expired	Refresh
scope_not_authorized	Missing permission	Reconnect
rate_limit_exceeded	Too many requests	Retry
spam_risk_*	Content flagged	User error
file_format_check_failed	Invalid format	User error
unaudited_client_can_only_post_to_private	Dev mode	Private only

Twitter/X Error Codes

Code	Meaning	Action
invalid_grant	Token revoked	Reconnect
usage-capped	Rate limited	Retry
duplicate	Same content exists	User error
186	Tweet too long	User error

Bluesky Error Codes

Code	Meaning	Action
ExpiredToken	JWT expired	Auto-refresh
InvalidToken	Bad token	Reconnect
XRPCNotSupported	App password lacks DM	Use full auth

Reddit Error Codes

Code	Meaning	Action
invalid token	Expired	Refresh
not allowed to submit	Subreddit restriction	User error
RATELIMIT	Too fast	Retry with delay
NO_LINKS	Links not allowed	User error

Telegram Error Codes

Code	Meaning	Action
message too long	>4096 chars	Truncate
chat not found	Invalid chat ID	User error
bot was blocked	User blocked bot	User error

---

6. Platform Quirks

JavaScript Large Integer IDs (Instagram/Facebook)

Instagram IDs exceed MAX_SAFE_INTEGER (17+ digits):

function safeJsonParse(text: string) {
  // Wrap large integers in quotes before parsing
  const safe = text.replace(/"id"\s*:\s*(\d{15,})/g, '"id":"$1"');
  return JSON.parse(safe);
}

Twitter Character Counting

function countTwitterCharacters(text: string): number {
  let count = 0;

  // URLs always count as 23 characters
  const urlRegex = /https?:\/\/[^\s]+/g;
  const urls = text.match(urlRegex) || [];
  const textWithoutUrls = text.replace(urlRegex, '');

  count += urls.length * 23;

  // Emojis and CJK count as 2
  for (const char of textWithoutUrls) {
    count += char.match(/[\u{1F600}-\u{1F64F}]|[\u4e00-\u9fff]/u) ? 2 : 1;
  }

  return count;
}

Twitter Character Limits by Tier

Tier	Limit
Free	280
Premium	4,000
Premium+	25,000

LinkedIn Text Escaping

Reserved characters: | { } [ ] ( ) < > # \ * _ ~

Note: @ is deliberately NOT escaped to avoid \@ showing in posts. URN mentions @[Name](urn:li:person:ID) and hashtags #tag are preserved automatically.

function escapeLinkedInText(text: string): string {
  // Reserved chars (excluding @ to preserve readability)
  const reserved = /[\|\{\}\[\]\(\)\<\>\#\\\*\_\~]/;

  let output = '';
  let i = 0;

  while (i < text.length) {
    // Preserve URN mentions: @[Display Name](urn:li:person:ID)
    if (text[i] === '@' && text[i + 1] === '[') {
      const closeBracket = text.indexOf(']', i + 2);
      if (closeBracket !== -1 && text.substring(closeBracket + 1, closeBracket + 9) === '(urn:li:') {
        const closeParen = text.indexOf(')', closeBracket + 9);
        if (closeParen !== -1) {
          output += text.substring(i, closeParen + 1);
          i = closeParen + 1;
          continue;
        }
      }
    }

    // Preserve hashtags: #word
    if (text[i] === '#' && /[a-zA-Z0-9_]/.test(text[i + 1] || '')) {
      output += text[i++];
      while (i < text.length && /[a-zA-Z0-9_]/.test(text[i])) {
        output += text[i++];
      }
      continue;
    }

    // Escape reserved characters
    output += reserved.test(text[i]) ? '\\' + text[i] : text[i];
    i++;
  }

  return output;
}

TikTok UX Compliance Requirements

TikTok requires full UX compliance for API audit:

• User must manually select privacy level (no defaults)
• Must show comment/duet/stitch toggles
• Commercial content disclosure with user confirmation
• Content preview before upload
• Express consent declaration

Reddit User-Agent Requirement

Reddit strictly enforces descriptive user agents:

// BAD - will be blocked
headers['User-Agent'] = 'axios/1.0';

// GOOD - descriptive format
headers['User-Agent'] = 'MyApp/1.0 (by /u/developer_username)';

Telegram HTML Subset

Only these HTML tags are supported:

<b>, <strong>       <!-- bold -->
<i>, <em>           <!-- italic -->
<u>                 <!-- underline -->
<s>, <strike>, <del><!-- strikethrough -->
<code>              <!-- monospace -->
<pre>               <!-- code block -->
<a href="...">      <!-- link -->
<tg-spoiler>        <!-- spoiler -->
<blockquote>        <!-- quote -->

---

7. Special Protocols

AT Protocol (Bluesky)

Bluesky uses AT Protocol, not OAuth:

Key Concepts:

• DID (Decentralized Identifier): User's permanent ID (e.g., did:plc:abc123)
• PDS (Personal Data Server): Where user data lives
• Handle: Human-readable name (e.g., user.bsky.social)

Rich Text Facets:

Mentions and links use byte-offset positioning:

function createFacets(text: string): Facet[] {
  const facets: Facet[] = [];
  const encoder = new TextEncoder();

  // Find mentions
  const mentionRegex = /@([a-zA-Z0-9.-]+)/g;
  let match;

  while ((match = mentionRegex.exec(text)) !== null) {
    const beforeText = text.slice(0, match.index);
    const byteStart = encoder.encode(beforeText).length;
    const byteEnd = byteStart + encoder.encode(match[0]).length;

    facets.push({
      index: { byteStart, byteEnd },
      features: [{
        $type: 'app.bsky.richtext.facet#mention',
        did: await resolveDid(match[1])
      }]
    });
  }

  return facets;
}

Snapchat AES-256-CBC Encryption

Snapchat requires media encryption before upload:

import crypto from 'crypto';

function encryptForSnapchat(buffer: Buffer): {
  encrypted: Buffer;
  key: string;
  iv: string;
} {
  const key = crypto.randomBytes(32); // 256 bits
  const iv = crypto.randomBytes(16);  // 128 bits

  const cipher = crypto.createCipheriv('aes-256-cbc', key, iv);
  const encrypted = Buffer.concat([
    cipher.update(buffer),
    cipher.final()
  ]);

  return {
    encrypted,
    key: key.toString('base64'),
    iv: iv.toString('base64')
  };
}

---

8. Quick Debugging Checklist

When a post fails:

1. Check token validity - Is the access token expired?
2. Check rate limits - Hit daily/hourly limits?
3. Check media URL - Can the platform fetch it directly?
4. Check media specs - Right format, size, dimensions, aspect ratio?
5. Check the 2207051 case - Did it post despite the error?
6. Check account status - Is the account restricted?
7. Check subreddit rules - (Reddit) Links allowed? Flair required?
8. Check user-agent - (Reddit) Descriptive enough?
9. Check bot permissions - (Telegram) Bot in chat with send rights?

---

9. Recommended Architecture

your-app/
├── lib/
│   ├── platforms/
│   │   ├── base.ts           # Abstract base class
│   │   ├── instagram.ts
│   │   ├── tiktok.ts
│   │   ├── twitter.ts
│   │   ├── bluesky.ts        # AT Protocol
│   │   ├── snapchat.ts       # With encryption
│   │   └── ...
│   ├── utils/
│   │   ├── rate-limiter.ts
│   │   ├── media-handler.ts
│   │   ├── error-mapper.ts
│   │   └── encryption.ts     # For Snapchat
│   └── queue/
│       └── scheduler.ts

---

10. Platform Comparison Matrix

Feature	Instagram	TikTok	Twitter	LinkedIn	YouTube	Facebook	Threads	Pinterest	Bluesky	Snapchat	GBP	Reddit	Telegram
OAuth	2-step	Standard	PKCE	Standard	Google	Standard	2-step	Basic	AT Proto	Basic	Google	Standard	Bot Token
Token Life	60d	2y+	2h+refresh	365d refresh	1y	60d+	60d	N/A	Auto	N/A	1y	Permanent	N/A
Video	Yes	Yes	Yes	Yes	Yes	Yes	Yes	Yes	Yes	Yes	No	No	Yes
Carousel	10	35	4	20	No	10	10	No	4	No	No	Gallery	Album 10
Scheduling	API	Draft	No	API	API	API	API	No	API	No	No	No	No
DMs	Yes	No	Yes	Yes	No	Yes	No	No	Yes	Yes	No	Yes	Yes
Analytics	Yes	Yes	Yes	Yes	Yes	Yes	Yes	Yes	No	No	Limited	No	Limited

---

About This Guide

This guide is maintained by Late, built from real patterns learned while scheduling 1M+ posts across all 13 platforms.

Every error code, edge case, and quirk documented here comes from production experience. The Instagram 2207051 gotcha? We discovered it after hours of debugging. The Snapchat encryption requirement? Learned the hard way.

Building a social media app? If you'd rather not implement and maintain all these integrations yourself, Late's API handles the complexity for you: OAuth, media processing, rate limits, error handling, and scheduling across all 13 platforms with a single integration.

---

Maintained by Late - Social Media Scheduling API for Developers