Error Handling

Error Response Format

Every non-2xx response returns a flat JSON envelope:

{
  "error": "Post not found.",
  "code": "NOT_FOUND"
}

Stability Contract

• code values are stable once shipped. Build retries, alerting, and i18n against them.
• The error message can change freely. Treat it as display-only.
• New codes may be added at any time. Removing a code is a breaking change.

HTTP Status Codes

Common Error Codes

This list is not exhaustive; new codes ship without notice. Handle unknown codes with a generic fallback.

Platform Errors

When an upstream platform rejects a publish, the failure lands on the destination, not just the HTTP response. Every destination carries its own outcome:

{
  "post": {
    "id": "1699f415-7fb6-43f4-9d2a-c447491f32a8",
    "status": "partial",
    "destinations": [
      {
        "platform": "x",
        "status": "published",
        "externalPostId": "1960956321831854280",
        "externalUrl": "https://x.com/acme/status/1960956321831854280",
        "errorCode": null,
        "errorMessage": null
      },
      {
        "platform": "instagram",
        "status": "failed",
        "errorCode": "MEDIA_TOO_LARGE",
        "errorMessage": "Video exceeds Instagram's 100 MB limit."
      }
    ]
  }
}

Post status summarizes the destinations: published when all succeeded, partial when some did, failed when none did. A terminal failure also fires the post.platform.failed webhook carrying the same errorCode / errorMessage pair — see webhooks.

Publishing Is Not Retried

A publish attempt is final. When a destination cannot be published, Onepostly marks it failed with the platform's own errorCode and errorMessage, and never submits it again. Waiting will not change the outcome.

That makes the failing destination the whole story. To publish the content again, create a new post once you have fixed the cause. Conditions that clear on their own arrive as their own codes, so you can tell a temporary platform state from a permanent rejection.

Common Publishing Failures

Webhook Reliability

If you use webhooks to track post status:

• Deliveries are at-least-once; you may receive duplicates. Dedupe by the stable event id.
• Failed deliveries are retried up to 5 times on 408, 429, 5xx, and network errors.
• Delivery history (status, attempts, last response) is available per endpoint through the API and dashboard.

Best Practices

• Branch on code, never on error text.
• Handle 429 by sleeping for Retry-After (or details.retryAfterSeconds).
• Treat 500/503 as transient and retry with backoff; treat 4xx as caller-fixable.
• Read the failing destination, not just post status — one post can succeed on X and fail on Instagram.
• Watch authHealth on connections to catch token expirations before they fail a publish.
• Use webhooks instead of polling for status changes.
• Log the full envelope (code, param, details) when reporting issues.