Social Media API Errors: Platform Directory and Triage Guide
Use this guide when social media API errors cause a publishing request to fail and you need to decide what to fix first. Start with the platform directory to find the relevant reference, then use the cross-platform failure matrix and triage workflow below to distinguish authentication, permission, content-policy, media-format, and quota or rate-limit problems before retrying. The directory covers Instagram, X (Twitter), TikTok, Facebook, LinkedIn, Bluesky, Pinterest, Threads, and YouTube, with each platform page intended to explain the errors that occur in its own publishing flow.
What this reference covers and how to use it
Platform documentation often assumes you already know which layer raised an error and what context surrounds it. This directory is organized to close that gap: pick the platform first, then read its error families in the context of the operation you attempted. A publishing failure can originate in credentials, account permissions, content policy, media processing, app status, or quota and rate limits. Treating all of those as a generic retry problem wastes time and can repeat a failure that will not change until something else changes. The matrix and workflow below give you a consistent way to classify a failure before you act.
Platform error directories
Instagram API errors cover the Instagram Content Publishing API, including the causes behind publishing failures and the guidance specific to that flow. X (Twitter) API errors cover duplicate detection, tier caps, and URL blocks among the common publishing failures developers encounter. TikTok API errors cover the TikTok Content Posting API surface, including auth, spam detection, video format, app status, and publishing constraints. Facebook Graph API errors cover auth, page permissions, content policy, and rate limits for Facebook publishing. LinkedIn API errors cover publishing to personal profiles and organization pages. Bluesky entries focus on AT Protocol errors seen when posting through the Bluesky PDS. Pinterest API errors cover pin creation, including video covers, auth, rate limits, and media format constraints. Threads API errors cover auth tied to Instagram, media processing, and video format. YouTube Data API errors cover uploads, metadata, and quota, including quotaExceeded.
Cross-platform failure matrix by error family
Use the failure matrix to map a symptom to the most likely layer. If the error mentions credentials, token expiry, or account connection, check auth first. If the account is connected but cannot act on a page, profile, or organization, check permissions. If the request is rejected for content reasons, check policy and duplicate or spam rules. If media is rejected or processing fails, check format, size, duration, and cover requirements. If the error mentions quota, tier caps, or rate limits, stop retrying immediately and check allowance and timing. This ordering matters because a media fix will not resolve an auth failure, and a credential refresh will not resolve an exhausted quota.
Triage workflow: identify layer, check auth and permissions, check media, check quota, then retry or escalate
First, identify the layer from the error code and message, and record the platform, operation, and timestamp. Second, check auth and account connection, including whether the token or session is still valid and whether the correct account is selected. Third, check permissions for the specific destination, such as a page, profile, or organization, rather than assuming a connected account can publish everywhere. Fourth, check media format and processing requirements, including file type, dimensions, duration, size, and cover image rules. Fifth, check quota, tier, and rate-limit state. Only then decide whether to retry, change the request, ask the user to reconnect or grant access, or escalate. Retry only when the underlying condition can plausibly change, such as a transient processing failure, and avoid immediate retries for auth, policy, permission, and quota failures.
Worked triage example
Consider a YouTube upload that returns quotaExceeded. The triage path is different from a media-format rejection. First, confirm the operation was an upload and note the timestamp and account context. Second, check whether the failure is a quota condition rather than an auth or metadata problem, because quotaExceeded points to allowance rather than credentials. Third, check the current quota or usage state and the timing of the next allowance window before scheduling another attempt. Fourth, do not change the video file or metadata in response to a quota error, since neither is the cause. Finally, escalate to the account owner or administrator if the quota cannot be increased or the workload must move to a different approved project, and record the error code and timestamp so the next attempt is not made blindly.
What to capture when reporting an error
When reporting an error, capture enough context to reproduce the classification without exposing secrets. Record the platform, the operation attempted, the exact error code and message, the timestamp, the account context, and a summary of the media or content involved. Include the request identifier if one is present. Do not include access tokens, client secrets, or other credentials. This checklist turns a vague report such as publishing failed into a triage-ready record that can be matched against the platform directory and the failure matrix.
| Platform | Error family named in source | Likely layer | First check | User action needed |
|---|---|---|---|---|
| Content Publishing API publishing errors | Publishing / media / auth | Account connection and media requirements | Reconnect, adjust media, or correct the request | |
| X (Twitter) | Duplicate detection, tier caps, URL blocks | Content policy / quota / policy | Whether content is duplicate, URL is blocked, or tier cap applies | Change content or URL, or wait for allowance |
| TikTok | Auth, spam detection, video format, app status, publishing constraints | Auth / policy / media / app status | Credentials, spam rules, video format, and app status | Reconnect, revise content or video, or resolve app status |
| Auth, page permissions, content policy, rate limits | Auth / permission / policy / rate limit | Page permission for the destination and rate-limit state | Grant page access, revise content, or wait | |
| Publishing to personal profiles or organization pages | Auth / permission | Correct profile or organization destination and permission | Select the correct destination or grant access | |
| Bluesky | AT Protocol errors through the Bluesky PDS | Protocol / PDS | PDS response and account context | Correct the request or escalate with protocol context |
| Video covers, auth, rate limits, media format constraints | Media / auth / rate limit | Cover and media format, then auth and rate limit | Fix cover or media, reconnect, or wait | |
| Threads | Auth tied to Instagram, media processing, video format | Auth / media processing | Instagram-tied auth and video format | Reconnect or adjust video |
| YouTube | Uploads, metadata, quota, quotaExceeded | Upload / metadata / quota | Quota state when quotaExceeded is returned | Wait for quota, adjust metadata, or escalate to account owner |
Error families are summarized by platform; see the platform page for specific codes.
| Check | Question to answer | If it fails |
|---|---|---|
| Layer | Which layer raised the error: auth, permission, policy, media, app status, or quota? | Classify before retrying |
| Auth | Is the correct account connected and is the credential still valid? | Ask the user to reconnect |
| Permissions | Can this account publish to this specific page, profile, or organization? | Ask for the missing permission or correct destination |
| Media | Does the file meet format, size, duration, and cover requirements? | Adjust the media and resubmit |
| Quota and rate limits | Is quota, tier, or rate allowance exhausted? | Wait or escalate; do not retry immediately |
| Report context | Are platform, operation, error code, timestamp, and account context recorded? | Complete the record before escalating |
Use this checklist before escalating a publishing failure.
{
"platform": "youtube",
"operation": "upload",
"error_code": "quotaExceeded",
"timestamp_utc": "<ISO-8601 timestamp>",
"account_context": "<account identifier supplied by the caller>",
"media_context": "<format, duration, and size summary>",
"request_id": "<provider or gateway request identifier, if present>"
}