Social Media API Error Handling

Social media API error handling comes down to one question asked over and over: retry, or give up. Answer it wrong in one direction and you publish the same post twice to a customer's audience. Answer it wrong in the other and you fail a post that would have succeeded on the second attempt. This is a classification problem, not a networking problem, and the classification is different for every platform.

The only question that matters

A publish failed. You have a status code, maybe a platform-specific error code, maybe a string. You have to decide, right now, whether to try again.

The two mistakes are not symmetrical.

Retrying a terminal error is cheap but noisy. You burn rate limit, you delay the eventual failure notification, and the customer waits longer to learn something you already knew. Annoying, recoverable.

Retrying a non-idempotent success is expensive. The platform accepted the post, the response never reached you, and you post again. The customer's followers see it twice. That is a support ticket, a refund conversation, and on some platforms a spam flag on the account.

So the bias is not "retry aggressively". The bias is know which operations are safe to repeat, and be conservative everywhere else.

Three buckets

Every error goes into one of three categories, and the third is the interesting one.

The rule for unknown is the whole design. If you treat everything unclassified as retryable, you will eventually duplicate a post. If you treat everything unclassified as terminal, every platform change becomes an outage. The resolution is that idempotency decides, not the error.

Two lists cover most of the transport layer regardless of platform:

const RETRYABLE_HTTP_STATUS_CODES = new Set([
  408, 425, 429, 500, 502, 503, 504, 520, 522, 524,
]);

const NETWORK_TRANSIENT_CODES = new Set([
  "ETIMEDOUT", "EAI_AGAIN", "ECONNRESET", "ECONNABORTED",
  "ENETUNREACH", "EHOSTUNREACH", "EADDRNOTAVAIL", "EADDRINUSE", "ENETDOWN",
]);

One deliberate omission: EPIPE is not in that list. A broken pipe can happen mid-write on a POST that the server already accepted. Classifying it as blanket-retryable is exactly how you double-post. Handle it per caller, only where the operation is idempotent.

Classification by platform

The transport layer is the easy part. Platform error codes are where the work is. This is a condensed view of what we classify in production, assembled over three years of watching these APIs fail and correcting the table each time one of them surprised us. Meta's error reference is the closest any platform comes to publishing its own version.

Three rows in there are counterintuitive enough to call out.

Google's quotaExceeded is terminal, but rateLimitExceeded is retryable. They read like synonyms. They are not. Rate limit means you went too fast and can slow down. Quota exceeded means you spent the day's allocation, and on YouTube that resets at midnight Pacific. No backoff within a job's lifetime survives that.

Meta's 2207042 is the Instagram 24-hour publishing cap, and it is terminal on purpose. It is a rolling limit of 25 posts per 24 hours. No retry budget can outlast it, so parking the post in a retry state for hours just delays a failure the customer needs to know about now.

Pinterest error 30 is retryable and error 2 is not, and neither is self-describing. This is the general shape of the problem: the codes carry no semantics you can infer. You either maintain the table or you guess.

Some classification is inevitably string matching, because platforms return prose. Regex on error messages is fragile and we treat it as a fallback, not a foundation: an upstream wording change silently reclassifies an error, so anything matched by pattern should be logged loudly enough that you notice the drift.

Where a retry duplicates the post

This is the table that should drive your retry policy, and almost nobody publishes it.

Our retry policies follow directly from that table. A normal publish gets 3 attempts with a 3-minute initial interval and exponential backoff. A YouTube upload gets 3 attempts, a 60-minute budget and a 2-minute heartbeat, because a large video legitimately takes longer than a publish and a dead worker needs detecting in minutes rather than at the end of the hour. Reddit and Facebook video get exactly one attempt, and the first failure is final.

That last one feels wrong the first time you write it. A single transient network blip fails the post permanently. It is still correct, because the alternative is a customer's audience seeing the same video twice and no way to tell which failure caused it.

When the failure is a lie

Some errors arrive after the platform already did the thing.

The pattern: your request times out or returns a 5xx, but the post is live. This happens most often on Instagram's media_publish step and on any platform where the publish is slow enough for a proxy timeout to fire before the response comes back.

If you retry blindly, you duplicate. If you fail blindly, the customer sees "failed" next to a post that is visibly on their profile, which is worse for trust than a plain failure.

The fix is a verification step before the retry:

async function publishWithVerification(account, post) {
  try {
    return await platform.publish(account, post);
  } catch (err) {
    if (!isRetryable(err)) throw err;

    // Before retrying, ask the platform what it actually has.
    // Look for something that identifies THIS post, not just "any recent post".
    const existing = await platform.findRecentPost(account, {
      since: post.attemptStartedAt,
      idempotencyHint: post.clientReference,
    });

    if (existing) {
      // The failure was a lie. Record the success and stop.
      return { id: existing.id, permalink: existing.permalink, recovered: true };
    }

    throw err; // Genuinely failed. Let the retry policy handle it.
  }
}

Two things make this work in practice. Carry your own reference into the post where the platform allows it, even if it is only in internal metadata, so the lookup is exact rather than heuristic. And window the lookup to the current attempt, or a customer who legitimately posted something similar five minutes ago gets matched to the wrong item.

Not every platform gives you a usable lookup. Where it does not, the honest answer is to lean terminal and let the customer decide, rather than guessing.

Backoff that means something

The generic advice is "use exponential backoff". Here is what the numbers actually need to be.

Match the initial interval to the failure you are backing off from. A network blip clears in seconds. Media transcoding takes minutes. Meta's posting rate limits clear in tens of minutes. Starting at 3 minutes with a coefficient of 2 gives you 3, 6, 12 minutes, which covers transcoding and most rate limits without holding a worker slot for an hour.

Cap total attempts low. Three is enough for genuinely transient errors. Anything that survives three attempts over 20 minutes is not transient, it is a problem someone needs to look at.

Some failures deserve a much longer park. TikTok's publish confirmation can take up to an hour for large files, so the fallback path there waits 4 hours between attempts rather than 3 minutes. Retrying a slow platform fast is just a way of failing faster.

Never retry into a rolling cap. Instagram's 25 posts per 24 hours, YouTube's daily quota, TikTok's "too many pending shares". Fail fast, surface it, and let scheduling handle it. Sitting in a retry loop against a 24-hour window is a worker held hostage for a day.

Related: the rate limits for every platform determine most of these numbers, and a large share of "errors" are actually media that never should have been sent, which is covered in media requirements per platform.

The shorter path

Roughly two hundred error codes across fifteen platforms, a retry policy per operation rather than per platform, an idempotency table you have to derive by breaking things, and a verification step for the failures that are not failures. It is a lot of machinery to keep a scheduled post from going out twice.

bundle.social's error reference documents what each code means and what to do about it. The classification above runs on our side, built from three years of production failures across every platform we support, so a terminal error fails immediately with a message you can show a customer instead of sitting in a retry loop for twenty minutes on its way to the same outcome.

Frequently asked questions

Which social media API errors should I retry?

Transport-level failures (408, 425, 429, 5xx, and network timeouts) plus platform codes explicitly documented as transient, such as Meta #4 and #9 or TikTok 40901. Everything about permissions, tokens, invalid parameters, media validation and duplicate content is terminal and will fail identically on the second attempt.

How do I avoid double-posting when I retry?

Decide per operation, not per platform. Retry only where the operation is idempotent or resumable, such as YouTube's resumable upload. Where it is not, such as Reddit submit or Facebook video, allow exactly one attempt and treat the first failure as final.

What do I do with an error code I have never seen?

Treat it as retryable only if the operation is safe to repeat, and log it prominently. Unknown codes are the main way platform changes reach you, and the log is how you notice before customers do.

Why did my post publish even though the API returned an error?

Because the platform completed the work and the response was lost, usually to a timeout. Before retrying a transient failure, query the platform for a post matching the current attempt. If it is there, record the success rather than trying again.

Keep reading

• Social Media API Rate Limits: Every Platform Compared
• Facebook API Permissions and App Review
• A Developer's Guide to the Facebook Graph API