Error Handling

Error Response Format

Every non-2xx response returns a flat JSON envelope modeled on Stripe's error shape:

{
  "error": "budgetAmount is required",
  "type": "invalid_request_error",
  "code": "missing_required_field",
  "param": "budgetAmount",
  "docUrl": "https://docs.zernio.com/guides/error-handling"
}

Stability contract

• type and 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.

Error Types

Common Error Codes

Platform Errors

When an upstream platform (Meta, Google, TikTok, LinkedIn, Pinterest, X) rejects a request, Zernio surfaces a platform_error envelope with the original payload passed through for inspection.

{
  "error": "Google rejected the ad: NOT_ENOUGH_SQUARE_MARKETING_IMAGE_ASSET",
  "type": "platform_error",
  "code": "platform_api_error",
  "platform": "google",
  "platformError": {
    "code": 3,
    "message": "Request contains an invalid argument.",
    "details": [ { "errors": [ { "errorCode": { "assetError": "NOT_ENOUGH_SQUARE_MARKETING_IMAGE_ASSET" }, "message": "Too few." } ] } ]
  }
}

• platform_error returns the upstream 4xx status when the platform indicated bad input, or 502 Bad Gateway when the platform returned 5xx / didn't indicate a status.
• Inspect platformError for platform-specific error codes you may want to map for retries or end-user messages.
• platform identifies which upstream surfaced the error, so one handler can branch by integration.

Post Publishing Failures

When a scheduled post fails to publish to one or more platforms, the post status reflects the outcome:

Each platform entry in the post has its own status and error fields:

{
  "post": {
    "status": "partial",
    "platforms": [
      { "platform": "twitter", "status": "published", "platformPostUrl": "https://twitter.com/..." },
      { "platform": "instagram", "status": "failed", "error": "Media processing failed: video too short for Reels" }
    ]
  }
}

Common publishing errors

Retrying failed posts

For failed or partial posts, use the retry endpoint:

const { post } = await zernio.posts.retryPost('post_123');

result = client.posts.retry("post_123")

curl -X POST "https://zernio.com/api/v1/posts/post_123/retry" \
  -H "Authorization: Bearer YOUR_API_KEY"

Only the failed platforms are retried; already-published platforms are skipped.

Account Health

Proactively check if your connected accounts are healthy before publishing:

const health = await zernio.accounts.getAccountHealth();

health = client.accounts.get_health()

curl "https://zernio.com/api/v1/accounts/health" \
  -H "Authorization: Bearer YOUR_API_KEY"

The health check endpoint returns token validity, permissions status, and recommendations for each account.

Webhook Reliability

If you use webhooks to track post status:

• Webhooks are delivered at least once (you may receive duplicates); dedupe by event id.
• Failed deliveries are retried with exponential backoff.
• You can view delivery logs via the webhook logs endpoint.

Best Practices

• Branch on type and code, never on error text.
• Handle 429 by respecting the Retry-After header.
• Treat platform_error upstream 4xx as caller-fixable (bad input forwarded from the platform) and 5xx / 502 as transient.
• Monitor account health periodically to catch token expirations early.
• Use webhooks instead of polling for post status updates.
• Log errors with full context, include the request body and the entire response envelope (including platformError) for debugging.