Errors

Understand Postifys publishing API error responses, common failure causes, and how to recover from media, auth, and platform permission issues.

Last updated: 2026-07-24 · Technical source: live Postifys API behavior and API reference

Error response shape

{
  "success": false,
  "error": {
    "message": "Platform error details"
  }
}

Form-based browser flows may redirect with query-string error codes instead of JSON.

Common publishing failures

• FACEBOOK_PAGE_ID is not set - pass pageId or connect/configure a default Page.
• INSTAGRAM_ACCOUNT_ID is not set - pass instagramAccountId or connect a default professional account.
• Missing/expired META_ACCESS_TOKEN (or other platform token) - reconnect the account in Postifys.
• Media URL not publicly reachable - host on a public HTTPS URL or use proxyDownload / Drive sharing correctly.
• Platform permission not approved - the connected account or app lacks the required scope/product.

How to think about HTTP status

• Auth failures typically mean the API key/session is missing or invalid - recheck Authentication and GET /api/key/test.
• Validation failures usually include a clear error.message about missing fields or unsupported types.
• Platform rejects can still return structured JSON with the provider message; use that text, not only the HTTP code.
• Media queue create returns 202 when a background job is accepted - poll status before assuming the file is ready.

Recovery checklist

1. Confirm /health is healthy if many jobs fail at once.
2. Open Post History and copy the failure reason.
3. Verify the destination account still appears in connections and is authorized.
4. Validate media: public URL, correct type (image vs Reel/video), Drive share settings.
5. Retry the failed job from the dashboard when supported, or resubmit the API call after fixes.
6. If TikTok “succeeded” but is not public, complete the post in the TikTok creator inbox.

Retry

Failed Facebook/Instagram publish attempts can be retried from Post History with the same text, media, platform, and target account (see API reference retry route). Fix the underlying cause first to avoid repeated identical failures.