Errors

​

Deprecation Notice

​

Standardized Error Format

{
  errorsVerbose: {
    INSTAGRAM: { /* error object */ } | null,
    TIKTOK: { /* error object */ } | null,
    FACEBOOK: { /* error object */ } | null,
    // ... other platforms
  }
}

​

Error Schema

{
  code: string | null;              // Stable error code (e.g., "IG:190", "HTTP:429", "TT:40001")
  errorMessage: string | null;      // Developer-facing error message from the platform
  isTransient: boolean | null;      // Whether the error is temporary and retry is recommended
  httpStatus: number | null;        // HTTP status code if applicable
  meta: any | null;                 // Additional debugging information (trace IDs, subcodes, etc.)
  userFacingMessage: string | null; // User-friendly error message for display
}

​

Field Descriptions

• code: A stable, stringified error code that identifies the specific error type. The code follows a pattern of PLATFORM:ERROR_CODE (e.g., IG:190 for Instagram error 190, HTTP:429 for rate limit). This code remains consistent and can be used programmatically to handle specific error cases.
• errorMessage: The raw error message returned by the social media platform’s API. This is intended for developers and may contain technical details about what went wrong.
• isTransient: A boolean flag indicating whether the error is temporary. If true, the operation can be retried after a delay (often indicated in the meta field). If false, the error requires manual intervention or configuration changes.
• httpStatus: The HTTP status code from the platform’s API response, if available. Common codes include 429 (rate limit), 401 (authentication error), 403 (permission denied), and 5xx (server errors).
• meta: Additional metadata and debugging information specific to each platform. This may include:
  • Trace IDs for support requests
  • Rate limit reset timestamps
  • Error subcodes
  • Validation details
  • Retry-after headers
  • Platform-specific error context
• userFacingMessage: A user-friendly error message suitable for displaying to end users. This message is crafted to be understandable without technical knowledge and provides actionable guidance when possible.

​

How Error Handling Works

1. Error Capture: The raw error from the platform API is intercepted
2. Error Parsing: The error is parsed and normalized into our standardized format
3. Error Classification: The error is classified as transient or non-transient
4. Error Enrichment: Additional context and debugging information is added
5. Error Return: The standardized error is returned in the errorsVerbose field

​

Platform-Specific Error Codes

​

Error Types

​

Transient Errors

• Rate Limits (isTransient: true): The platform’s rate limit has been exceeded. Check the meta field for retry_after information.
• Server Errors (isTransient: true): The platform’s API is experiencing temporary issues (HTTP 5xx errors).
• Network Errors (isTransient: true): Connection timeouts or network-related issues.

​

Non-Transient Errors

• Authentication Errors (isTransient: false): Invalid or expired access tokens. The user needs to reconnect their social account.
• Permission Errors (isTransient: false): Insufficient permissions to perform the operation. The user needs to grant additional permissions.
• Validation Errors (isTransient: false): Invalid post content (e.g., text too long, unsupported media format). The post needs to be modified.
• Quota Exceeded (isTransient: false): Platform-specific quotas have been reached (e.g., daily post limit).

​

Migration Guide

​

Before (will be deprecated)

const post = await bundlesocial.post.postGet({ id: postId });

// Old way - simple string per platform
if (post.errors) {
  if (post.errors.INSTAGRAM) {
    console.log("Instagram error:", post.errors.INSTAGRAM); // Simple string
  }
  if (post.errors.TIKTOK) {
    console.log("TikTok error:", post.errors.TIKTOK); // Simple string
  }
}

​

After

const post = await bundlesocial.post.postGet({ id: postId });

// New way - structured error per platform
if (post.errorsVerbose) {
  // Check Instagram errors
  if (post.errorsVerbose.INSTAGRAM) {
    const igError = post.errorsVerbose.INSTAGRAM;
    console.log("Error code:", igError.code);
    console.log("Developer message:", igError.errorMessage);
    console.log("User message:", igError.userFacingMessage);
    console.log("Can retry?", igError.isTransient);
    
    // Handle rate limits
    if (igError.httpStatus === 429) {
      const retryAfter = igError.meta?.retry_after;
      console.log(`Rate limited. Retry after ${retryAfter} seconds`);
    }
    
    // Handle authentication errors
    if (igError.code?.includes("190")) {
      console.log("Token expired. User needs to reconnect account.");
    }
  }
  
  // Check TikTok errors
  if (post.errorsVerbose.TIKTOK) {
    const ttError = post.errorsVerbose.TIKTOK;
    console.log("TikTok error:", ttError.errorMessage);
    console.log("User should see:", ttError.userFacingMessage);
  }
  
  // Or loop through all platforms
  for (const [platform, error] of Object.entries(post.errorsVerbose)) {
    if (error) {
      console.log(`${platform} failed:`, error.userFacingMessage);
      if (error.isTransient) {
        console.log(`  → Can retry this error`);
      }
    }
  }
}

​

Best Practices

1. Check isTransient: Always check the isTransient flag to determine if retrying is appropriate.
2. Use Error Codes: Use the code field to programmatically handle specific error types rather than parsing error messages.
3. Display User Messages: Show userFacingMessage to end users and log errorMessage for debugging.
4. Handle Rate Limits: When encountering rate limits, respect the retry_after value in the meta field.
5. Log Metadata: Include the meta field in your logs to help with debugging and support requests.
6. Monitor Error Patterns: Track error codes and types to identify recurring issues with specific platforms or accounts.

​

Support

• The error code
• The errorMessage
• The meta field contents
• The platform and post ID