Skip to content

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.

Cross-platform failure matrix by error family
PlatformError family named in sourceLikely layerFirst checkUser action needed
InstagramContent Publishing API publishing errorsPublishing / media / authAccount connection and media requirementsReconnect, adjust media, or correct the request
X (Twitter)Duplicate detection, tier caps, URL blocksContent policy / quota / policyWhether content is duplicate, URL is blocked, or tier cap appliesChange content or URL, or wait for allowance
TikTokAuth, spam detection, video format, app status, publishing constraintsAuth / policy / media / app statusCredentials, spam rules, video format, and app statusReconnect, revise content or video, or resolve app status
FacebookAuth, page permissions, content policy, rate limitsAuth / permission / policy / rate limitPage permission for the destination and rate-limit stateGrant page access, revise content, or wait
LinkedInPublishing to personal profiles or organization pagesAuth / permissionCorrect profile or organization destination and permissionSelect the correct destination or grant access
BlueskyAT Protocol errors through the Bluesky PDSProtocol / PDSPDS response and account contextCorrect the request or escalate with protocol context
PinterestVideo covers, auth, rate limits, media format constraintsMedia / auth / rate limitCover and media format, then auth and rate limitFix cover or media, reconnect, or wait
ThreadsAuth tied to Instagram, media processing, video formatAuth / media processingInstagram-tied auth and video formatReconnect or adjust video
YouTubeUploads, metadata, quota, quotaExceededUpload / metadata / quotaQuota state when quotaExceeded is returnedWait for quota, adjust metadata, or escalate to account owner

Error families are summarized by platform; see the platform page for specific codes.

Triage checklist
CheckQuestion to answerIf it fails
LayerWhich layer raised the error: auth, permission, policy, media, app status, or quota?Classify before retrying
AuthIs the correct account connected and is the credential still valid?Ask the user to reconnect
PermissionsCan this account publish to this specific page, profile, or organization?Ask for the missing permission or correct destination
MediaDoes the file meet format, size, duration, and cover requirements?Adjust the media and resubmit
Quota and rate limitsIs quota, tier, or rate allowance exhausted?Wait or escalate; do not retry immediately
Report contextAre platform, operation, error code, timestamp, and account context recorded?Complete the record before escalating

Use this checklist before escalating a publishing failure.

Error report checklist example
{
  "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>"
}