Errors

Every failed request returns a structured error body using RFC 9457 problem details (which obsoletes RFC 7807), served with the Content-Type: application/problem+json media type. The HTTP status line tells you the category; the body tells you what went wrong and, where relevant, a stable machine-readable code, the offending field, or which publish target failed.

There are two layers of failure to reason about. Request errors are returned synchronously from the API call (a bad body, a missing key, a not-found id). Publishing errors happen asynchronously after a post is accepted, when a target fails to reach a platform — these never change the HTTP status of the original POST /posts call; they surface on the post’s targets[] instead.

The problem+json envelope

Every synchronous error shares the same top-level shape:

{
  "type": "about:blank",
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "One or more target accounts were not found."
}

HTTP status codes

The API uses a small, conventional set of status codes. Each maps to a fixed title.

Error-code catalog

Where a stable identifier is useful, the API and pipeline emit a machine-readable code alongside the human-readable detail. Branch on code (and the HTTP status), never on detail. There are two families: request codes on synchronous API errors, and per-target error_codes recorded on a publish target when it fails.

Request error codes

Emitted in the code field of a synchronous problem+json response.

Publish target error codes

Recorded in a target’s error_code (see per-target errorsbelow). These describe why a particular account’s publish failed, and whether PostFuze retries it.

Validation errors

When a request body fails schema validation, the response carries an errors array describing each offending field. Each entry is a validation issue with a path (the location in your JSON, as an array of keys/indices), a machine-readable code, and a message. A missing-or-malformed body on POST /posts returns 400 with these issues; schema failures raised deeper in the stack normalize to 422 with the same errors shape.

{
  "type": "about:blank",
  "title": "Bad Request",
  "status": 400,
  "detail": "Invalid request body.",
  "errors": [
    {
      "code": "too_small",
      "minimum": 1,
      "type": "array",
      "inclusive": true,
      "path": ["accounts"],
      "message": "Array must contain at least 1 element(s)"
    },
    {
      "code": "invalid_type",
      "expected": "string",
      "received": "number",
      "path": ["containers", 0, "content"],
      "message": "Expected string, received number"
    }
  ]
}

The path points straight at the field: ["containers", 0, "content"] means containers[0].content. Use it to attach errors to the right input without string-matching the message.

Common error situations by resource

These are the most common (status, detail) pairs you will encounter across the core resources.

Partial success and per-target errors

A POST /posts that targets several accounts is accepted as a single unit and returns 201 immediately — before any platform has been contacted. Publishing then happens asynchronously, one target per account, each retrying independently. Because targets are independent, a post can partially succeed: some accounts publish while others fail.

You observe the outcome by retrieving the post and inspecting its targets:

• status — the target’s lifecycle state: pending, queued, published, failed (a transient failure that will retry), dead (a terminal failure, dead-lettered), or canceled.
• error_code — a stable, machine-readable failure reason (see the table below). null until something fails.
• error_message — the underlying message from the platform or transport, for debugging. Not stable; do not branch on it.

The post-level status rolls these up: published when every target succeeded, partial when at least one succeeded and at least one failed terminally, and failed when all targets failed or were canceled.

{
  "id": "p1a2b3c4-0000-4a9f-9b1c-2e7d6f0a1234",
  "status": "partial",
  "targets": [
    {
      "id": "t_0001",
      "platform": "x",
      "status": "published",
      "platform_post_id": "1799012345678901234",
      "platform_post_url": "https://x.com/acme/status/1799012345678901234",
      "error_code": null,
      "error_message": null
    },
    {
      "id": "t_0002",
      "platform": "youtube",
      "status": "dead",
      "platform_post_id": null,
      "platform_post_url": null,
      "error_code": "token_expired",
      "error_message": "401 Unauthorized: The access token has expired."
    }
  ]
}

The error_code values are assigned by PostFuze when a target fails:

Transient failures back off with full-jitter exponential delay (capped at one hour) until they either succeed or exhaust the target’s retry budget, at which point the target becomes dead. If you have webhooks configured, a post.published event fires once at least one target succeeds, and post.error fires when all targets fail.

Handling errors in code

A robust client branches on the HTTP status, reads detail for context, walks errors for validation problems, and retries only the statuses that are safe to retry.

type Problem = {
  type: string;
  title: string;
  status: number;
  detail?: string;
  errors?: { path: (string | number)[]; code: string; message: string }[];
};

export class PostfuzeError extends Error {
  // retryAfter comes from the Retry-After response HEADER (429/503), not the problem body.
  constructor(readonly problem: Problem, readonly retryAfter?: number) {
    super(problem.detail ?? problem.title);
    this.name = 'PostfuzeError';
  }
  get status() {
    return this.problem.status;
  }
}

export async function request(path: string, init: RequestInit = {}) {
  const res = await fetch(`https://api.postfuze.com/api/v1${path}`, {
    ...init,
    headers: {
      Authorization: `Bearer ${process.env.POSTFUZE_API_KEY}`,
      'Content-Type': 'application/json',
      ...init.headers,
    },
  });

  if (res.ok) return res.json();

  // Errors are problem+json; parse defensively in case a proxy returns plain text.
  const problem = (await res.json().catch(() => ({
    type: 'about:blank',
    title: res.statusText,
    status: res.status,
  }))) as Problem;

  if (problem.status === 422 && problem.errors) {
    for (const issue of problem.errors) {
      console.error(`  ${issue.path.join('.')}: ${issue.message}`);
    }
  }

  // Retry-After is a response header (seconds), not part of the problem body.
  const retryAfter = Number(res.headers.get('retry-after')) || undefined;
  throw new PostfuzeError(problem, retryAfter);
}

// Retry only the statuses that are safe to retry.
const RETRYABLE = new Set([429, 500, 502, 503, 504]);

export async function withRetry<T>(fn: () => Promise<T>, attempts = 3): Promise<T> {
  for (let i = 0; ; i++) {
    try {
      return await fn();
    } catch (err) {
      const status = err instanceof PostfuzeError ? err.status : 500;
      if (i >= attempts - 1 || !RETRYABLE.has(status)) throw err;
      const retryAfter = err instanceof PostfuzeError ? err.retryAfter : undefined;
      const delayMs = (retryAfter ?? 2 ** i) * 1000;
      await new Promise((r) => setTimeout(r, delayMs));
    }
  }
}