Error Handling

Error Response Format

All API errors return a consistent JSON structure:

{
  "error": "Human-readable error message",
  "details": {}
}

The details object is optional and contains additional context when available (e.g., validation errors, platform-specific information).

HTTP Status Codes

Post Publishing Failures

When a 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 late.posts.retryPost('post_123');

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

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

This retries only the failed platforms - already-published platforms are skipped.

Account Health

Proactively check if your connected accounts are healthy before publishing:

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

health = client.accounts.get_health()

curl "https://getlate.dev/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, note that:

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

Best Practices

• Always check the response status code before parsing the body
• Handle 429 responses by respecting the Retry-After header
• Monitor account health periodically to catch token expirations early
• Use webhooks instead of polling for post status updates
• Log errors with context - include the request body and response for debugging