Rate Limits

Two layers of limits apply to every request: your OmniPost workspace plan, and — once a request reaches a real platform — that platform's own limits.

Plan limits

These apply per workspace, regardless of how many API keys or connected accounts you have.

"Posts / month" counts successful POST /v1/uploadcalls that create a post — one post counts once regardless of how many platforms it targets. Requests that fail validation (4xx before a post is created) don't count against it. Sandbox posts count toward the same monthly cap as live posts, since sandbox mode still exercises your workspace's infrastructure.

Exceeding the monthly post cap returns 403 plan_limit_exceeded. Exceeding connected-account or API-key caps returns the same code from POST /v1/accounts/:platform/connect or key creation, respectively. Exceeding the requests-per-minute ceiling returns 429 rate_limited.

Platform-imposed limits

Once a target reaches a real platform (live keys only), that platform's own rate limits apply on top of your OmniPost plan limit. OmniPost surfaces these as platform_rate_limited on the affected target rather than rejecting the whole request — see Errors.

Full per-platform detail, including media upload limits, lives on each platform guide.

Handling 429s

A 429 response always includes a Retry-After header in seconds. Respect it — hammering the API during a rate-limit window extends the penalty on some downstream platforms.

async function uploadWithBackoff(body, attempt = 0) {
  const res = await fetch("https://api.omnipost.dev/v1/upload", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.OMNIPOST_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(body),
  });

  if (res.status === 429 && attempt < 5) {
    const retryAfter = Number(res.headers.get("Retry-After") ?? "1");
    await new Promise((r) => setTimeout(r, retryAfter * 1000));
    return uploadWithBackoff(body, attempt + 1);
  }

  if (!res.ok) {
    const { error } = await res.json();
    throw new Error(`${error.code}: ${error.message}`);
  }

  return res.json();
}

• Cap retries (5 is a reasonable default) and surface a hard failure rather than retrying forever.
• For bulk publishing, spread requests out proactively rather than bursting up to the limit and relying on retries.
• Workspace-level 429s and platform-level platform_rate_limited target errors both benefit from the same backoff strategy, but the latter doesn't block the rest of your request — only the affected target.