Error Handling in TikTok API Integrations: A Developer's Survival Guide

Error 2200002 — Scope Not Authorized

The most common error in new integrations. Your access token doesn't include the scope your request requires. Root cause: the user authorized your app before you added a new scope (e.g., video.upload). Fix: force re-authorization with the updated scope list. In production, store the scopes granted at auth time and proactively flag tokens that are missing required scopes before making the request.

Error 2200010 — Access Token Expired

TikTok access tokens expire within 24–72 hours depending on the flow. Build a refresh-before-expiry system: store token_expires_at in your database, and run a background job that refreshes any token expiring within the next 2 hours. Do NOT wait for a 2200010 to trigger a refresh — that means you've already dropped a request. Use the refresh_token endpoint and handle the case where the refresh token itself has expired (user must re-auth).

Error 40002 — Rate Limit Exceeded

TikTok's documented rate limits are conservative, but the practical limits are stricter and not always published. Implement exponential backoff with jitter starting at 1 second, capping at 64 seconds. Track rate limit headers (X-RateLimit-Remaining, X-RateLimit-Reset) if returned. For bulk posting pipelines, use a token-bucket queue that distributes requests across time — never batch-fire concurrent uploads against the same app credentials.

Error 2200006 — Video Processing Failed (Async)

This is the killer. Your POST to /video/upload/ returns a 200 with a publish_id, but the video never appears. The failure happens during TikTok's async processing pipeline. You MUST implement a polling mechanism against /video/query/ using the publish_id. Poll at 10s, 30s, 60s, 120s intervals. If status is PROCESSING_FAILED after 5 minutes, log the failure_reason, alert, and enqueue a retry with the original asset. This is not optional — it's the core reliability mechanism for any posting integration.

Error 2200009 — Content Policy Violation

TikTok's content moderation runs async and can reject videos that passed your own checks. Common causes: watermarks from competitor platforms, music with licensing restrictions, or video content that triggers automated classifiers. Maintain a rejection log per client/account. If the same video is rejected twice, flag it for manual review rather than retrying — you'll just burn credits and risk the account being flagged.

Error 2200067 — Daily Upload Limit Reached

New accounts and unverified apps have per-account daily upload caps. This is separate from rate limiting — it's a per-creator-account restriction. Fix: distribute your posting volume across multiple accounts and time zones. Track daily_post_count per account in your database and route uploads to accounts with remaining capacity. This is one of the core reasons multi-account infrastructure exists.

Account-Level Circuit Breakers

Don't just track errors globally — track error rate per account. If a specific account starts returning repeated 2200009s or processing failures, put that account into a 'degraded' state and route new jobs to healthy accounts. Resume posting to the degraded account after a cooldown period. This prevents one bad account from poisoning your error metrics and keeps your overall pipeline throughput stable.

Token Pool Management

With many accounts, you'll have many OAuth tokens in various states of freshness. Build a token registry that tracks expiry per account, runs pre-emptive refresh jobs, and flags accounts that require re-authentication. Never let a job hit a 2200010 in production — it means your token management layer has a gap. Query your token registry before dispatching any job and block jobs for expired-token accounts before they hit the API.

Posting Queue Sharding

Shard your posting queue by account rather than running a single global queue. This prevents one account's rate limit or daily cap from blocking posts destined for other accounts. Each shard handles its own backoff, retry scheduling, and capacity tracking. Combine with a router layer that selects the optimal account shard based on remaining daily capacity, geo requirements, and account health score.

Async Result Reconciliation

Run a scheduled reconciliation job (every 15 minutes) that queries /video/query/ for all publish_ids that were submitted in the last 24 hours and haven't reached a terminal state. This catches silent processing failures that don't trigger webhooks or callbacks. Cross-reference against your internal posting log and alert on any publish_id that has been in PROCESSING state for more than 10 minutes.