Social media API errors: Diagnose before retrying

Diagnose a social media API error by identifying who returned it and whether the post was already created. Authentication, permission checks, rate limits, and a network rejecting media are different incidents. Repeating the same create request is not a universal repair and can turn an outage into duplicate posts.

Developer operations / A failure-classification runbook

In short

• Capture the HTTP status, response body, and original job identifiers before changing anything.
• Fix credentials or permissions deliberately; wait on rate limits; reconcile uncertain writes before replaying them.
• Track scheduling acceptance separately from eventual publication on each destination account.

I am PostSider’s founder. The concrete examples below use its public API, checked against the application implementation and official documentation on October 18, 2026. This is an incident guide, not a replacement for the first-post API tutorial.

First establish which request failed

An HTTP error from your scheduler and an error from Instagram are not interchangeable. Record the request host, method, path, time, and job stage before choosing a response.

A useful incident record contains your internal job ID, the intended channel, the saved UTC schedule, the HTTP status, and the response body. Add the scheduler’s post ID if creation returned one. For a multi-channel job, keep each returned ID separately: success on one destination does not establish success on another.

Do not put authorization headers, OAuth tokens, or signed media URLs into general logs. Preserve a sanitized error message and any provider trace identifier in a restricted incident record. If an HTML error page appears where JSON was expected, investigate the gateway or destination host rather than assuming the application rejected your payload.

Also record whether the failure happened during account listing, media upload, post creation, or later publication. The same numeric status can mean different things at those boundaries. A successful connection check only proves that particular check succeeded.

A 401 needs the response body, not an automatic reconnect

A 401 usually points to credentials, but the body decides the repair. PostSider also returns 401 with No subscription found when the authenticated organization has no subscription row in billing-enabled operation.

For an organization API key, send the raw key in the Authorization header to https://api.postsider.com/public/v1. Do not add Bearer to that key or copy a social network access token into its place. OAuth credentials are a separate authentication path; do not generalize one credential’s header rules to every integration.

Start with a read-only request such as listing integrations. Verify that the deployed worker actually received the intended environment variable and that the key belongs to the right organization. A locally working key does not prove that a scheduled worker has the same configuration.

If the response says Invalid API key or Invalid OAuth token, repair that credential. If it says No subscription found, inspect the account’s subscription instead. Repeatedly rotating keys will not create a missing subscription, and reconnecting Instagram will not repair scheduler authentication.

The PostSider API overview documents the supported public base URL and organization-key authentication. Keep this distinction in your support playbook so an authentication incident does not trigger unrelated account changes.

A 403 is not a synonym for an expired token

A forbidden operation can involve role permissions, the wrong organization, unavailable account access, or a provider-specific permission. Read the message and identify the authority that denied the action.

Ask whether the caller can access this exact resource, not whether the caller can access anything. An account may be visible to one administrator but unavailable to the user who authorized an integration. A working read permission also does not establish a publishing permission.

PostSider’s error reference notes that some forbidden flows are remapped to 401. Therefore, build diagnostics around both status and structured error content, rather than assuming the status alone uniquely identifies the problem. Do not tell every operator with a 403 to refresh their token.

Keep two other gates separate. A 402 can identify a plan entitlement or quota problem. A 423 with error: publishing_paused means organization publishing is paused. The latter is a deliberate safety state, not an expired credential. Ask the authorized operator why it was paused; never have a recovery worker silently resume publishing.

After correcting access, retry only the intended operation. Avoid using a broader administrator credential as a permanent workaround for a role mismatch.

A 429 requires shared backpressure

Rate limiting means the caller is sending requests faster than the service permits. Honor the response’s Retry-After value before another attempt, and slow the workers sharing that budget.

PostSider exposes X-RateLimit-Limit and X-RateLimit-Remaining. Its public API limiter is organization-scoped, so reducing traffic in one process may not help if several other workers continue polling. Coordinate the queue instead of adding a private sleep to each failing request.

Keep reads in that budget. Listing integrations repeatedly and polling every post can consume requests even when you create little content. Cache stable account mappings where appropriate, use bounded status checks, and stop polling completed jobs.

A rate limit from the destination network is a different layer. Waiting for the scheduler’s HTTP budget does not reset Instagram’s publishing capacity. Preserve the provider error and follow that provider’s recovery guidance. If a response lacks a usable retry hint, use a conservative bounded delay and escalation policy, not a tight retry loop.

Adding jitter after the required waiting period can prevent many workers restarting together. Give each job an attempt limit and an overall deadline, especially when the intended publishing time is passing.

A 400 or 409 usually needs a decision before another write

Validation and conflict errors are not transient merely because they interrupted automation. Inspect the fields and the saved operation before choosing whether anything should be sent again.

A 400 can name a channel whose content or provider settings failed validation. Fix that requirement rather than resubmitting the same invalid body. A draft saving successfully does not prove that its media and publishing settings will pass scheduling checks.

For 409, PostSider’s idempotency implementation distinguishes an invalid key, a key already associated with a different request, and a matching request still processing. Those cases need different handling. Wait on a processing operation; investigate a changed-body conflict; correct an invalid key only after establishing the original outcome.

The comparison is based on the parsed request body’s serialized JSON. Keep the original payload file instead of rebuilding it with a different date or property order. A corrected request is a deliberate revision, not an invisible retry. Reconcile any existing post before assigning a new key to a replacement.

For key design and persistence details, use the dedicated social posting idempotency guide. This runbook’s boundary is deciding whether a retry is appropriate, not promising exactly-once delivery.

A timeout leaves the result unknown until you reconcile it

Losing the response does not prove the server rejected the request. Treat a timed-out create operation as an uncertain write, even if your HTTP client labels it a network failure.

If you received a post ID, read that exact post before creating another. If you did not, preserve the original key and body, allow time for processing, and inspect the narrow schedule window and target channel. Compare content and schedule together; identical text alone is a poor job identifier.

A bounded replay with the same idempotency key and unchanged body can recover a completed result. It is not a guarantee that every failure path is replay-safe: the controller releases a claimed key when creation throws, and validation and access checks can run before a replay is returned. A later error is not proof that nothing was written earlier.

For a 5xx, first check whether the saved job is already present. Retry only under the same operation policy, with backoff and a deadline. Stop and escalate if evidence remains inconsistent. Creating fresh UUIDs until something returns 200 hides the incident rather than resolving it.

Successful creation starts a second diagnostic timeline

An accepted job can fail later when publication reaches the destination network. Keep that asynchronous outcome separate from the HTTP result that created the job.

In PostSider, a create response supplies post IDs. Read the post’s records to inspect state, publishDate, and any available publication URL. QUEUE is pending work, not proof that the post is live. An ERROR needs investigation of the channel and provider failure before creating a replacement.

A publication webhook can confirm success, but do not wait for a failure event that your integration does not provide. The webhook confirmation guide explains the separate receiving path. Use status reads for unresolved jobs and verify the destination post when a URL is available.

For Instagram-specific failures, continue with the publishing rejection diagnostic. For a repeatable pre-release exercise, use the API testing checklist. Finish an incident by recording the cause, the original job’s final outcome, and the change that prevents the same failure class.

Sources and implementation boundary

Checked October 18, 2026: PostSider API errors, API overview, and posts reference. The distinctions for authentication, idempotency conflicts, organization rate limiting, and publishing pause were also checked in the application code. This guide does not claim that a live account was deliberately rate-limited or that a provider failure was induced in production.

Lukasz Blania is the founder of PostSider, a social media scheduling product with a human dashboard and API access.