Validation

This guide covers how PostPost validates posts before scheduling to prevent publish failures, including what gets validated, the validation response format, error codes, and best practices for avoiding validation errors.

Overview

Posts are validated before scheduling to catch issues that would cause publishing failures on target platforms. Each social media platform has unique requirements for content length, media types, file sizes, and video durations. PostPost validates your posts against these platform-specific limits and returns detailed error information so you can fix issues before scheduling.

Validation runs when you change a post's status to scheduled in the PostPost dashboard. The REST API create-post endpoint does not trigger full validation -- it only performs basic field presence checks. See the "When Validation Occurs" section below for details.

When Validation Occurs

Validation runs automatically on these API calls:

Note: The POST /api/v1/create-post API endpoint does not run post validation (postValidationService.validatePostGroup). It only performs basic field presence checks (content, platforms, scheduledTime format). Full validation only runs in the dashboard flow when updating a post to scheduled status. The PUT /api/v1/update-post/:id endpoint also does not invoke the validation service -- it only accepts status and scheduledTime fields (for rescheduling or changing draft/scheduled status).

If validation fails with blocking errors, the API returns a 400 status code with details about what needs to be fixed. Warnings are returned but do not block the operation.

What Gets Validated

Content Length

Each platform has a maximum character limit. Some platforms also have minimum requirements.

Media Requirements

Some platforms require media, while others support text-only posts.

Media File Sizes

Media Formats

Critical: Instagram API only accepts JPEG images. PNG and GIF will fail validation.

Video Duration Limits

Validation Response Format

Note: The structured validation response below (with validation.errors[], validation.warnings[], and validation.summary) is returned by the dashboard validation endpoint only. The REST API create-post endpoint does not run the full validation service and will not return this format (it only performs basic field presence checks). The REST API update-post endpoint and MCP update_post tool also do not invoke the validator.

When validation errors occur, the API returns a 400 status code with a structured response:

{
  "error": "Validation failed",
  "validation": {
    "valid": false,
    "errors": [
      {
        "platform": "instagram",
        "code": "MEDIA_REQUIRED",
        "message": "Instagram posts require media",
        "field": "media",
        "severity": "error"
      },
      {
        "platform": "tiktok",
        "code": "VIDEO_REQUIRED",
        "message": "TikTok posts require a video",
        "field": "video",
        "severity": "error"
      }
    ],
    "warnings": [
      {
        "platform": "twitter",
        "code": "CONTENT_TOO_LONG",
        "message": "Content exceeds Twitter/X's 280 character limit (currently 450)",
        "field": "content",
        "severity": "warning",
        "constraint": "maxLength",
        "currentValue": 450
      }
    ],
    "summary": {
      "affectedPlatforms": ["instagram", "tiktok", "twitter"],
      "errorCount": 2,
      "warningCount": 1
    }
  }
}

Response Fields

Error/Warning Object Fields

Error Codes Reference

Content Errors

Reserved -- not currently emitted by the validation service.

| CONTENT_REQUIRED | Text content is required but missing | Add text content to the post |

Reserved -- not currently emitted by the validation service. | CONTENT_OR_MEDIA_REQUIRED | Either text or media is needed | Add content or attach media | | THREAD_PART_TOO_LONG | A single thread part exceeds the platform's per-part character limit | Break the thread part into smaller segments. (This code is defined in the @postpost/platform-limits package. Threading validation may occur in a separate service.) | | INVALID_PLATFORM_CONTENT | Content contains elements not supported by the platform | Remove unsupported content elements. (This error code is defined in the codebase but not currently emitted by the validation service.) |

Media Errors

Reserved -- not currently emitted by the validation service.

Video Errors

Reserved -- not currently emitted by the validation service.

Platform Errors

System Errors

Examples

Validation Error: Missing Media for Instagram

When posting to Instagram without media:

Request:

{
  "content": "Check out our latest update!",
  "platforms": ["twitter-123", "instagram-456"]
}

Response (400):

{
  "error": "Validation failed",
  "validation": {
    "valid": false,
    "errors": [
      {
        "platform": "instagram",
        "code": "MEDIA_REQUIRED",
        "message": "Instagram posts require media",
        "field": "media",
        "severity": "error"
      }
    ],
    "warnings": [],
    "summary": {
      "affectedPlatforms": ["instagram"],
      "errorCount": 1,
      "warningCount": 0
    }
  }
}

Validation Error: Video Required for TikTok

When posting an image to TikTok (video-only platform):

Request:

{
  "content": "New product announcement!",
  "platforms": ["tiktok-789"],
  "media": [{ "type": "image", "url": "https://..." }]
}

Response (400):

{
  "error": "Validation failed",
  "validation": {
    "valid": false,
    "errors": [
      {
        "platform": "tiktok",
        "code": "VIDEO_REQUIRED",
        "message": "TikTok posts require a video",
        "field": "video",
        "severity": "error"
      }
    ],
    "warnings": [],
    "summary": {
      "affectedPlatforms": ["tiktok"],
      "errorCount": 1,
      "warningCount": 0
    }
  }
}

Validation Error: Content Too Long

When content exceeds Twitter's 280 character limit:

Threading note: This example shows CONTENT_TOO_LONG as an "error" with severity: "error". However, on threading-capable platforms (Twitter/X, Threads) with threading enabled, this would be a warning (severity: "warning") instead, because the content will be automatically split into a thread. The example below assumes threading is disabled.

Response (400):

{
  "error": "Validation failed",
  "validation": {
    "valid": false,
    "errors": [
      {
        "platform": "twitter",
        "code": "CONTENT_TOO_LONG",
        "message": "Content exceeds Twitter/X's 280 character limit (currently 450)",
        "field": "content",
        "severity": "error"
      }
    ],
    "warnings": [],
    "summary": {
      "affectedPlatforms": ["twitter"],
      "errorCount": 1,
      "warningCount": 0
    }
  }
}

Validation Error: Image Format Not Supported

When uploading a PNG to Instagram (JPEG only via API):

Response (400):

{
  "error": "Validation failed",
  "validation": {
    "valid": false,
    "errors": [
      {
        "platform": "instagram",
        "code": "MEDIA_TYPE_NOT_SUPPORTED",
        "message": "Image format \"image/png\" is not supported on Instagram",
        "field": "imageFormat",
        "severity": "error"
      }
    ],
    "warnings": [],
    "summary": {
      "affectedPlatforms": ["instagram"],
      "errorCount": 1,
      "warningCount": 0
    }
  }
}

Validation Error: Video Duration Exceeded

When a video exceeds platform limits:

Response (400):

{
  "error": "Validation failed",
  "validation": {
    "valid": false,
    "errors": [
      {
        "platform": "instagram",
        "code": "VIDEO_DURATION_EXCEEDED",
        "message": "Video duration (3m 0s) exceeds Instagram's 60s carousel limit",
        "field": "videoDuration",
        "severity": "error"
      },
      {
        "platform": "twitter",
        "code": "VIDEO_DURATION_EXCEEDED",
        "message": "Video duration (3m 0s) exceeds Twitter/X's 2m 0s limit",
        "field": "videoDuration",
        "severity": "error"
      }
    ],
    "warnings": [],
    "summary": {
      "affectedPlatforms": ["instagram", "twitter"],
      "errorCount": 2,
      "warningCount": 0
    }
  }
}

Validation Error: File Size Exceeded

When an image exceeds Bluesky's strict 1 MB limit:

Response (400):

{
  "error": "Validation failed",
  "validation": {
    "valid": false,
    "errors": [
      {
        "platform": "bluesky",
        "code": "MEDIA_SIZE_EXCEEDED",
        "message": "Image (2.5MB) exceeds Bluesky's 1.0MB limit",
        "field": "imageSize",
        "severity": "error"
      }
    ],
    "warnings": [],
    "summary": {
      "affectedPlatforms": ["bluesky"],
      "errorCount": 1,
      "warningCount": 0
    }
  }
}

Multiple Platform Errors

When a single post has issues on multiple platforms:

Response (400):

{
  "error": "Validation failed",
  "validation": {
    "valid": false,
    "errors": [
      {
        "platform": "instagram",
        "code": "MEDIA_TYPE_NOT_SUPPORTED",
        "message": "Image format \"image/png\" is not supported on Instagram",
        "field": "imageFormat",
        "severity": "error"
      },
      {
        "platform": "bluesky",
        "code": "MEDIA_SIZE_EXCEEDED",
        "message": "Image (2.5MB) exceeds Bluesky's 1.0MB limit",
        "field": "imageSize",
        "severity": "error"
      },
      {
        "platform": "tiktok",
        "code": "VIDEO_REQUIRED",
        "message": "TikTok posts require a video",
        "field": "video",
        "severity": "error"
      }
    ],
    "warnings": [],
    "summary": {
      "affectedPlatforms": ["instagram", "bluesky", "tiktok"],
      "errorCount": 3,
      "warningCount": 0
    }
  }
}

Best Practices

1. Validate content length client-side. Check character counts before sending the API request. Different platforms have different limits (Twitter: 280, LinkedIn: 3,000, Bluesky: 300).

2. Always use JPEG for Instagram. The Instagram API does not support PNG or GIF. Convert images to JPEG before uploading.

3. Compress images for Bluesky. Bluesky has a strict 1 MB limit. Use JPEG compression at 80-85% quality to stay under the limit.

4. Check video durations before uploading. Instagram Reels API maxes out at 3 minutes (180s), carousel videos at 60 seconds, Twitter at 2 minutes, TikTok at 10 minutes. Trim videos accordingly.

5. Use separate media for different platform groups. If posting to both image and video platforms, consider creating separate posts:

   • Image posts for Instagram, Twitter, LinkedIn
   • Video posts for TikTok, YouTube

6. Handle validation errors gracefully in your UI. Display platform-specific error messages so users know exactly what to fix.

7. Consider platform requirements when designing content. If targeting TikTok, always start with video. If targeting Instagram, prepare JPEG images.

8. Keep Bluesky image dimensions under 2000x2000 pixels. Larger images will fail validation.

9. For Telegram bots, keep captions under 1,024 characters. Bots cannot exceed this limit even though users can send 4,096 characters.

10. Test video FPS for TikTok. TikTok has minimum FPS requirements. Videos with very low frame rates will fail at publish time.

Common Issues