How-To Guide

How do you fix social media API errors?

Sort each social media API failure into authentication, throttling, payload or duplicate, retry only the transient ones, and fix the rest by platform code.

11 min read

By the Superdirector editorial team. Meta, Instagram, Threads, TikTok, YouTube, LinkedIn and X developer documentation, and three Blotato builder guides, read November 15, 2026.

At a glance

How do you fix social media API errors?

Read the error object first, then sort the failure into one of four classes: authentication, throttling, payload or duplicate. Authentication errors such as Meta's code 190 need a new token, not a retry. Throttling errors such as a 429 need a wait until the window resets. Payload errors, usually media that is not reachable or is the wrong format, need the file fixed. Only the transient classes belong in an automatic retry, and every retry needs its own caller-side record id so a timeout does not become a duplicate post.

  • Read the whole response body, including the code, subcode, message and trace id, before you decide anything.
  • Meta's 190, 463 and 467 mean an expired or invalid token, so reconnect instead of retrying.
  • A 429 is a window problem: read the reset value, wait, then retry once with backoff.
  • A media URL can answer 200 and still serve an HTML page, so check content type and size.
  • An asynchronous publish returns a submission id, and only a terminal status proves the post is live.
A 2x2 matrix sorts a failed publish into authentication, throttling, payload or duplicate, and each quadrant carries the one action that class allows.

The class decides the action: a new token, a wait, a fixed file, or a check of the original submission. Original diagram from Meta's Graph API error guide and the Blotato failure log, read November 15, 2026.

Superdirector

Make it work for your brand

Find it. Remake it. Post it. Superdirector turns the viral formats in your niche into your brand's carousels, X posts and video scripts, and keeps the calendar full.

Read the response body before the status code

A status code tells you that a request failed. It rarely tells you why. Meta opens its error guide with the plain fact that requests made to its APIs can result in several different error responses. The useful information sits in the body: a message, a numeric code, a subcode and a trace id. Two failed publishes can both come back as a 400 and mean completely different things.

When a publish call fails, capture the whole object before your code decides anything. Log the message, the code, the subcode, the trace id, the endpoint, the account and the time. Meta calls its trace value an internal support identifier, and it is the fastest thing to quote when you ask a provider what happened. Once you have the body on disk, the fix becomes an ordinary lookup.

FieldWhat it tells youExample from Meta
HTTP statusThat the request failed, and roughly which family of failure400 or 429
codeThe platform's own reason number190 is an expired access token
error_subcodeA narrower cause inside the code460 means the password changed
messageHuman-readable text, sometimes the only clue a wrapper gives youMessage describing the error
trace idA support handle for that one requestfbtrace_id

Meta's code 4 is a throttling signal. Code 190 is an expired token. Both can stop a post, and neither is fixed by the same branch of code. If your handler only looks at the HTTP status, both arrive as a failed request and your retry policy treats them the same.

Sort the error into one of four classes

Almost every publish failure belongs to one of four classes: authentication, throttling, payload, or duplicate. The class matters because it decides whether a retry is allowed. An authentication failure needs a new token. A throttle needs a wait. A payload failure needs the file or the request fixed. A duplicate needs the original submission checked before anything is resent.

ClassTypical signalCorrect action
AuthenticationMeta 190, 463 or 467; an invalid or expired tokenGet a new token or reconnect the account. Never retry blind.
ThrottlingHTTP 429; Meta code 4 or 17Read the reset time, wait, then retry once with backoff.
Payload and mediaMedia metadata failure, bad aspect ratio, missing scopeFix the file, the format or the app permission. A retry sends the same bad request.
DuplicateMeta code 506Look up the original submission before you resend.

The classes are not equally common. In one agency's 90-day log of 13 failed posts across 8 distinct error strings, nine of the 13 failures never reached a platform API at all. Most died on media before any platform saw the request. A retry handler aimed at rate limits would have defended the wrong door for almost every failure.

Match by class, not by an exact string. Match on the class, not on any one of those strings, because platforms reword messages and wrappers rename codes. Most write failures are permanent, so retrying into a rate limit converts one failed post into a throttled account.

Fix authentication and token errors

Authentication failures are the easiest class to identify and the hardest to automate. On Meta, 190 Access token has expired means the fix is a new access token. Codes 463 Expired and 467 Invalid Access Token say the same thing. None of them get better with a retry, because the credential itself is the problem.

Read the subcode before you rebuild the whole login flow. Meta's 458 App Not Installed means the user has not logged into your app, and 460 Password Changed points at the account's own password change. Code 492 Invalid Session is different again: the token is valid but its user lacks a role on the Page. Reconnecting fixes the first two and does nothing for the third.

Permission errors sit beside authentication and often get mistaken for it. TikTok requires that your app must be approved for the video.publish scope, and that the target TikTok user must have authorized your app for the video.publish scope. An app that skipped either step fails on publish with a permission error that looks like a broken token. Fix the app configuration, then reconnect.

Treat token expiry as a calendar event, not an exception. A retry loop cannot reconnect an account, so route the authentication class to a person with the account name and the timestamp. Everything else can stay in code.

Fix rate-limit and throttle errors

A 429 means the window is full. On X, exceeding limits results in a 429 error until the window resets, and those windows are usually 15 minutes or 24 hours. The response carries the numbers you need: x-rate-limit-remaining tells you how many calls are left in the current window. Read the reset time before you sleep, so the wait matches the platform instead of a guess.

Every platform counts differently, which is why one generic limiter fails. Instagram states that Instagram accounts are limited to 100 API-published posts within a 24-hour moving period. The same guide separately states that accounts are limited to 50 published posts within a 24-hour period in its carousel section. When a page argues with itself, read the account: Instagram offers a content_publishing_limit endpoint that reports the quota actually in force for that account.

X publishes a per-endpoint table. For publishing, POST /2/tweets 10,000/24hrs 100/15min gives you a daily application ceiling and a short per-user window. A burst that clears the day can still fail the fifteen-minute limit.

LinkedIn is the awkward one. Standard rate limits are not published in documentation, and these limits reset at midnight UTC every day. To learn your own ceiling you make one call and read the endpoint's usage in the Developer Portal Analytics tab. The alert email is not a safety net: LinkedIn says alerts are triggered only on application-level threshold breaches, and a quota alert can arrive one to two hours late.

For YouTube the upload bucket is simple to read. A videos.insert call costs 1 unit in the Video Uploads quota bucket and the file ceiling is 256GB. The widely repeated figure of six uploads a day is out of date; Blotato records that the default ceiling is 100 uploads a day, not six, though it also warns that rate-limit numbers are the most confidently wrong subject in this category. Check the platform page on the day you ship.

When you do retry, back off. Blotato's builder guide recommends that a client wait and retry with a growing delay rather than hammering the endpoint after a 429. And pace the writes before they hit a wall: the per-minute limits break agents first, and the daily ones catch the survivors, because an agent tends to generate its whole day's output in one burst.

Four platform cards show the window each counts: Instagram over 24 hours, X over 15 minutes and 24 hours, LinkedIn at midnight UTC and YouTube by quota.

Each platform counts a publish limit on its own window, so one requests-per-minute limiter fits none of them. Original diagram from X's rate-limit page, Meta's Instagram publishing guide, LinkedIn's limits page and YouTube's videos.insert reference, read November 15, 2026.

Fix media and payload errors

Media is the failure most guides rank too low. The 90-day log found that most failures happened before any platform call, and the single most common string was Failed to read media metadata. Is the file accessible and a valid media file?. The URL returned a healthy 200 and served an HTML confirmation page instead of the video. A status check saw nothing wrong.

So check more than the status. Never validate a media URL on status code alone and check content_type and size_download too. A media URL that answers 200 with text/html is not a video, and the platform will report the failure later as a metadata problem.

Expiring links are the second trap. A signed URL has a deadline, and a post scheduled for Tuesday holding a Friday-signed URL is a failure with a date on it. Resolve media to durable storage when you create the post, not when you publish it. Meta explains the same requirement plainly: We cURL media used in publishing attempts, so the media must be hosted on a publicly accessible server at the time of the attempt.

Format and scope errors are payload errors too. TikTok wants a supported container, and its guide says to ensure you have a video file in one of the supported formats, such as MP4 + H.264. A video hosted on a URL must use PULL_FROM_URL. TikTok also warns that all content posted by unaudited clients will be restricted to private viewing mode, so a publish call can succeed and reach almost nobody until the app passes audit.

Threads names its container failures. A container that is not published within a day returns a status of EXPIRED, because it was not published within 24 hours and has expired. When the cause is the file, a retry sends the same broken file, and retrying identical media will not help. Fix the file, then publish again.

A worked example puts a share link answering 200 with text/html at 2,431 bytes beside a direct download answering 200 with video/mp4.

Both answers carried the same status, and only one of them was the video. Original diagram from the Blotato 90-day failure log, read November 15, 2026.

Handle asynchronous results and duplicates

Many publish endpoints return a job, not a post. Blotato's API is explicit about its own shape: because our API returns a postSubmissionId rather than a result, all of this is asynchronous. The create call succeeds, the failure surfaces later against the record, and a client that stops at the create response never sees it.

The broader rule holds across platforms. Publishing is asynchronous on most platforms, so an accepted request is a receipt and not a delivered post. If your agent equates HTTP 200 with publication, it will report a clean week that never went out.

Poll to a terminal state and stop when you get there. Threads recommends that you query a container's status once per minute, for no more than 5 minutes, which gives the container time to finish without an infinite loop. A status still in progress is not a failure and not a success; it is a reason to look again later.

Duplicates are the other side of a timeout. If a create call times out on your side, it may still have published. Keep your own record id for each submission, and check the status of the original submission before you retry anything. On Meta, the protection that works is that lookup: a second publish of the same content returns code 506 Duplicate Post, which is the platform telling you the retry was the mistake.

A numbered flow runs from create to submission id to in progress, then splits into the two terminal outcomes, published or failed.

The create call returns a submission id, and only a terminal status proves the post went out. Original diagram from Blotato's asynchronous-publish guide and Threads' troubleshooting notes, read November 15, 2026.

Record failures so the next fix is faster

A failure log is worth more than a clever retry, because it tells you which class is actually costing you posts. Keep the raw string. Blotato puts it plainly: your agent will meet error strings that appear in no vendor's reference, and it should record the raw string rather than trying to classify it. Classification comes later, from the log, with the counts in front of you.

Log four things for every failure: the raw error object, the endpoint and account, the time, and the submission id if there was one. Then group by class and count by code. The 90-day example in this article exists because one team could pull its own failed posts and sort them, and the sorted list contradicted the ranking everyone repeats.

  1. Authentication: page a person with the account and the time.
  2. Throttling: record the reset time and retry once after it.
  3. Payload: keep the media URL, its content type and its size.
  4. Duplicate: log the submission id you checked before resending.

Then act on the class: alert a person for authentication, wait and back off for throttling, fix the file or the scope for payload failures, and check the original before any resend for duplicates. When the next error arrives, you start from a log instead of a guess.

Frequently asked questions

How do you fix social media API errors?

Read the error object first. It carries a code, a subcode, a message and usually a trace id, and those decide the fix. Sort the failure into one of four classes: authentication, throttling, payload or duplicate. Authentication needs a new token or a reconnect. Throttling needs a wait until the window resets. Payload failures, usually media, need the file or the request fixed. Duplicates need the original submission checked before you resend. Only the transient classes belong in an automatic retry.

What does a 429 error mean on a social media API?

A 429 means the request hit a rate limit. On X, exceeding a limit returns 429 until the window resets, and windows are usually 15 minutes or 24 hours. Read the reset header or the x-rate-limit-remaining value, wait for the reset, then retry once with a growing delay. Do not keep calling, because a retry storm keeps the window full.

Why did my post fail when the media URL returned 200?

A 200 from a URL only says the server answered. It can be an HTML error page, a login interstitial or a file that is no longer there. Check the content type and the downloaded size, not just the status. A Google Drive share link, for example, can return 200 with text/html instead of the video. Fetch or re-upload the file, then publish again, because retrying identical media will not help.

Should I retry a failed social media post?

Only for a transient failure. A 429 or a temporary platform error is worth one retry after the reset time, with backoff. An expired token, a missing permission, a rejected media file or a duplicate error will not change on a retry. Most write failures are permanent, so a blind retry can turn one failed post into a throttled account.

What is a duplicate post error?

Meta returns code 506 when the same post is published twice in a row. It usually means a create call timed out on your side and your code resent it after the first one had already succeeded. Keep your own record id for each submission and check the original submission before you resend; on Meta, that lookup is the protection that works.

How do I know an asynchronous post actually published?

Poll the submission to a terminal state. A create call that returns a submission id is a receipt, not a published post, and an HTTP 200 on the create call does not prove the post is live. Threads recommends querying a container's status once per minute for no more than five minutes, and a container that is not published within 24 hours expires.

Related practical guides

Turn the fix into a check

Add one handler per error class, pull your own failed posts, and sort them by code. If media failures dominate, fix the media path first, because it fails before the platform call and a retry cannot reach it.