Error Handling

SocialSyncerAPI uses standard HTTP status codes. All error responses return JSON with error and code fields.

Error Response Format

{
  "error": "Human-readable error message",
  "code": "MACHINE_READABLE_CODE"
}

HTTP Status Codes

400 — Bad Request

The request body is invalid or missing required fields.

{
  "error": "Platforms required for non-draft posts",
  "code": "VALIDATION_ERROR"
}

401 — Unauthorized

API key is missing or invalid.

{
  "error": "Invalid API key",
  "code": "AUTH_INVALID_KEY"
}

404 — Not Found

The requested resource doesn't exist.

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

429 — Rate Limited

You've hit the rate limit. Wait before retrying.

{
  "error": "Rate limit exceeded",
  "code": "RATE_LIMIT_EXCEEDED"
}

500 — Internal Server Error

Something went wrong on our end. These are rare — contact support if they persist.

{
  "error": "Internal server error",
  "code": "INTERNAL_ERROR"
}

Platform Errors

When a post fails on a specific platform, the error is included in the post response:

{
  "id": "post_abc123",
  "status": "partial",
  "platforms": [
    {
      "platform": "instagram",
      "status": "published",
      "platformPostId": "17841400123456789",
      "platformPostUrl": "https://instagram.com/p/ABC123"
    },
    {
      "platform": "tiktok",
      "status": "failed",
      "error": "Video processing failed: unsupported codec"
    }
  ]
}

Retrying Failed Posts

Use the retry endpoint to re-attempt failed platforms:

curl -X POST https://api.socialsyncerapi.com/v1/posts/post_abc123/retry \
  -H "Authorization: Bearer sk_your_api_key"

Error Handling Best Practices

Python

import httpx

def create_post(content, platforms):
    try:
        resp = httpx.post(
            "https://api.socialsyncerapi.com/v1/posts",
            headers={"Authorization": "Bearer sk_your_api_key"},
            json={
                "content": content,
                "platforms": platforms,
                "publishNow": True
            },
            timeout=30
        )
        resp.raise_for_status()
        return resp.json()
    except httpx.HTTPStatusError as e:
        if e.response.status_code == 429:
            # Rate limited — wait and retry
            retry_after = int(e.response.headers.get("Retry-After", 60))
            time.sleep(retry_after)
            return create_post(content, platforms)
        elif e.response.status_code >= 500:
            # Server error — retry with backoff
            time.sleep(5)
            return create_post(content, platforms)
        else:
            raise
    except httpx.TimeoutException:
        # Timeout — retry once
        return create_post(content, platforms)

Node.js

async function createPost(content, platforms) {
  const resp = await fetch("https://api.socialsyncerapi.com/v1/posts", {
    method: "POST",
    headers: {
      "Authorization": "Bearer sk_your_api_key",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({ content, platforms, publishNow: true })
  });

  if (resp.status === 429) {
    const retryAfter = resp.headers.get("Retry-After") || 60;
    await new Promise(r => setTimeout(r, retryAfter * 1000));
    return createPost(content, platforms);
  }

  if (!resp.ok) {
    const error = await resp.json();
    throw new Error(error.error);
  }

  return resp.json();
}