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.
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.
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.
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.
| Field | What it tells you | Example from Meta |
|---|---|---|
| HTTP status | That the request failed, and roughly which family of failure | 400 or 429 |
| code | The platform's own reason number | 190 is an expired access token |
| error_subcode | A narrower cause inside the code | 460 means the password changed |
| message | Human-readable text, sometimes the only clue a wrapper gives you | Message describing the error |
| trace id | A support handle for that one request | fbtrace_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.
| Class | Typical signal | Correct action |
|---|---|---|
| Authentication | Meta 190, 463 or 467; an invalid or expired token | Get a new token or reconnect the account. Never retry blind. |
| Throttling | HTTP 429; Meta code 4 or 17 | Read the reset time, wait, then retry once with backoff. |
| Payload and media | Media metadata failure, bad aspect ratio, missing scope | Fix the file, the format or the app permission. A retry sends the same bad request. |
| Duplicate | Meta code 506 | Look 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.
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.
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.
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.
- Authentication: page a person with the account and the time.
- Throttling: record the reset time and retry once after it.
- Payload: keep the media URL, its content type and its size.
- 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.