Recovery playbook

One page for diagnosing and recovering from any VoxBurst posting failure. Find your situation and follow the steps.

1. Validation error before the post is created (status 400)

The post was never created. The API returned an error immediately.

Diagnose: Read the error message — it usually names the field and what’s wrong.

validate_content(
  content: "your caption",
  platforms: ["INSTAGRAM"]
)

Common causes:

2. Post created but status stays pending or publishing

The post exists in VoxBurst but publishing hasn’t completed.

Check status:

get_post(postId: "post_abc123")

What to do:

• pending for less than 5 minutes: normal — posts go through a scheduling queue. Wait and re-check.
• pending for more than 10 minutes: check the VoxBurst dashboard for queue issues.
• publishing for more than 5 minutes: the publish attempt is in flight. Wait another minute, then check again.

3. Post status is failed (all platforms failed)

get_post(postId: "post_abc123")

Read platforms[].error for each platform to find the reason. Then:

Step 1 — Retry (for transient errors)

retry_post(postId: "post_abc123")

VoxBurst automatically retries up to 3 times with exponential backoff. If the failure was transient (network error, rate limit), this resolves it.

Step 2 — Fix and resubmit (for content/media errors)

If the error was caused by invalid media or caption:

# Get the postPlatformId from get_post's platforms[] array
curl -X POST https://api.voxburst.io/v1/posts/post_abc123/platforms/pp_xyz789/fix \
  -H "Authorization: Bearer vb_live_xxxxxxxxxxxxx" \
  -d '{ "mediaUrl": "https://cdn.example.com/corrected-image.jpg" }'

This resets the retry counter and resubmits with corrected media.

Common platform errors and fixes:

4. Post status is partial (some platforms succeeded, some failed)

Instagram published but Twitter failed. VoxBurst records this as partial.

get_post(postId: "post_abc123")

Look at platforms — entries with status: "published" succeeded, entries with status: "failed" need attention.

Retry only the failed platforms:

retry_post(postId: "post_abc123")

retry_post re-queues only failed platforms. Platforms that already published are never re-posted.

If a platform shows retryCount: 3 — it has exhausted automatic retries. Use the REST /fix endpoint to reset it:

curl -X POST https://api.voxburst.io/v1/posts/post_abc123/platforms/pp_failed_platform/fix \
  -H "Authorization: Bearer vb_live_xxxxxxxxxxxxx"

5. Media processing failure

The media upload succeeded but the file failed processing.

curl https://api.voxburst.io/v1/media/media_abc123 \
  -H "Authorization: Bearer vb_live_xxxxxxxxxxxxx"

Look for "status": "FAILED" and validationResults for the reason.

Common causes and fixes:

Upload a corrected file and get a new mediaId before retrying the post.

6. Account permission / auth failure

get_post(postId: "post_abc123")

platforms[].error will mention ACCOUNT_DISCONNECTED, INVALID_TOKEN, INSUFFICIENT_PERMISSIONS, or similar.

Fix:

1. Go to VoxBurst app → Settings → Connected Accounts
2. Find the affected account
3. Disconnect and re-connect it
4. Make sure to approve all requested permissions during re-connection

Then retry the post.

7. Retry vs recreate — when to do each

8. Delete and start over

Sometimes the simplest fix is to delete the post and create a fresh one:

delete_post(postId: "post_abc123")

Then create a new post with the corrected parameters.

Platform-specific recovery

For platform-specific failure details, see the individual platform failure cookbooks:

• Instagram recovery
• Twitter / X recovery
• LinkedIn recovery
• Facebook recovery
• Threads recovery
• YouTube recovery
• Bluesky recovery
• Mastodon recovery