Error Handling

​

Response shape

{
  "statusCode": 403,
  "code": "PLAN_LIMIT_POSTS",
  "message": "Your plan allows 100 posts/month.",
  "limit": 100,
  "current": 100,
  "requestId": "req_01HSAB7N4P9K2D6CXEZTQVRMW3"
}

​

Stability contract

• code and statusCode are stable. We will not change them without a major version bump. Add new codes to your switch as we ship new features; existing codes will keep their meaning.
• message is not stable. Copy may be tightened, translated, or re-phrased between releases. Show it; never === it.
• Extra fields are additive. A PLAN_LIMIT_POSTS error today carries limit + current; future versions may add resetAt. Treat the envelope as open-shape.

​

HTTP status codes

​

Error codes

​

Authentication & access

​

Plan limits & billing

​

Posts & publishing

​

Media

​

Generic & infrastructure

​

Handling errors in code

import Postbreeze, { APIError } from "@postbreeze/node";

const postbreeze = new Postbreeze({ apiKey: process.env.POSTBREEZE_API_KEY! });

try {
  await postbreeze.posts.create({
    content: "Launching today 🚀",
    platforms: [{ accountId: "soc_…" }],
  });
} catch (err) {
  if (!(err instanceof APIError)) throw err;

  switch (err.code) {
    case "PLAN_LIMIT_POSTS":
      // err.extras.limit, err.extras.current are present.
      alert(`You've used ${err.extras.current}/${err.extras.limit} this month.`);
      break;
    case "RETRY_COOLDOWN":
      await sleep(err.extras.retryAfterMs);
      // retry…
      break;
    case "INVALID_API_KEY":
      // Bubble up; user needs to re-issue.
      throw err;
    default:
      console.error(`API error [${err.code}] req=${err.requestId}: ${err.message}`);
      throw err;
  }
}

​

Retries

async function withRetry<T>(fn: () => Promise<T>, attempts = 5): Promise<T> {
  for (let i = 0; i < attempts; i++) {
    try {
      return await fn();
    } catch (err) {
      if (!(err instanceof APIError)) throw err;

      // Permanent: bail immediately.
      const permanent = ["VALIDATION_FAILED", "INVALID_API_KEY",
        "FORBIDDEN_WORKSPACE", "INSUFFICIENT_ROLE", "PLAN_LIMIT_POSTS",
        "PLAN_LIMIT_API_POSTS", "PLAN_LIMIT_WORKSPACES",
        "PLATFORM_ALREADY_CONNECTED", "MEDIA_IN_USE",
        "MUST_SPECIFY_EXACTLY_ONE"];
      if (permanent.includes(err.code)) throw err;

      // Honour an explicit Retry-After / retryAfterMs.
      const wait = err.extras.retryAfterMs
        ?? err.retryAfterHeader * 1000
        ?? Math.min(30_000, 1000 * 2 ** i);
      await new Promise((r) => setTimeout(r, wait));
    }
  }
  throw new Error("Exhausted retry attempts");
}

​

Idempotency

1. Use clientReferenceId. Pass a unique string (UUID, your own primary key) when creating a post. We dedupe within a 24-hour window — a retry with the same clientReferenceId returns the original post instead of creating a duplicate.
   await postbreeze.posts.create({
     clientReferenceId: "your-post-id-42",
     content: "…",
     platforms: [{ accountId: "soc_…" }],
   });
   
2. Search before retrying. If a retry feels risky, query GET /posts?workspaceId=…&scheduledAfter=… before the second attempt and check whether the first one already wrote the row.

​

Webhooks

• Dedupe on event.id (a ULID). Store the last N event IDs you’ve processed and short-circuit duplicates.
• Return 2xx fast. Acknowledge first, process async. Anything over 5 seconds eats into the next retry’s window.
• We back off at 30s, 2min, 10min, 1hr, 6hr, 24hr. After six failures, the delivery is marked DEAD and surfaces in Settings → Webhooks → Deliveries. No further attempts.
• Signature: every request carries an X-Postbreeze-Signature header — HMAC-SHA256(secret, rawBody) in hex. Verify before trusting the body.

​

Account health

​

Best practices

• Branch on code, never on message. Message text rotates; codes don’t.
• Always log requestId. It’s the only correlation key we have between your client and our server logs. Surface it in your own error reports.
• Show plan-limit errors with context. PLAN_LIMIT_* errors carry limit and current — surface “97/100 posts used this month” instead of a generic “quota reached.” Most users self-serve upgrade when shown the number.
• Don’t retry 4xx. Anything in the 400-range is your request being wrong, not our server. Retrying wastes quota and slows your user down.
• Use clientReferenceId for create calls. It’s the single cheapest way to make your integration idempotent.
• Pin to a major version. All endpoints live under /api/v1. We will introduce /api/v2 before we break anything in v1.