paperclipai/paperclip · error · Error

API error ${response.status}: ${bytes.toString("utf8")}

Error message

API error ${response.status}: ${bytes.toString("utf8")}

What it means

Thrown by the workspace org-output command (workspace.ts:140) when fetch() against /api/companies/{id}/{path} returns a non-OK HTTP status. The error message embeds the HTTP status code and the raw response body as UTF-8 for diagnostics.

Source

Thrown at cli/src/commands/client/workspace.ts:140

    { includeCompany: false },
  );
}

function addBinaryCompanyGet(parent: Command, name: string, description: string, path: string): void {
  addCommonClientOptions(
    parent
      .command(name)
      .description(description)
      .option("-C, --company-id <id>", "Company ID")
      .option("--out <path>", "Write output to file")
      .action(async (opts: OrgOutputOptions) => {
        try {
          const ctx = resolveCommandContext(opts, { requireCompany: true });
          const response = await fetch(buildApiUrl(ctx.api.apiBase, `${apiPath`/api/companies/${ctx.companyId}`}/${path}`), {
            headers: ctx.api.apiKey ? { authorization: `Bearer ${ctx.api.apiKey}` } : undefined,
          });
          const bytes = Buffer.from(await response.arrayBuffer());
          if (!response.ok) throw new Error(`API error ${response.status}: ${bytes.toString("utf8")}`);
          if (opts.out) {
            const { writeFile } = await import("node:fs/promises");
            await writeFile(opts.out, bytes);
            printOutput({ out: opts.out, bytes: bytes.byteLength }, { json: ctx.json });
            return;
          }
          process.stdout.write(bytes);
        } catch (err) {
          handleCommandError(err);
        }
      }),
    { includeCompany: false },
  );
}

function addCompanyPostJson(parent: Command, name: string, description: string, path: string): void {
  addCommonClientOptions(
    parent

View on GitHub (pinned to 67001ec6eb)

Solutions

1. Read the embedded status and body text: 401/403 → fix the API key; 404 → fix the company/path; 5xx → check server logs.
2. Confirm the API base URL and that ctx.api.apiKey is set (PAPERCLIP_API_KEY or login).
3. Verify --company-id exists and the user has access.
4. Retry once for transient 5xx; if persistent, inspect server logs.

Example fix

// before: 401 Unauthorized
// ensure API key is set
export PAPERCLIP_API_KEY=...
paperclipai ... workspace org-output --company-id X

async function ensureCompanyExportOk(baseUrl: string, apiKey: string | undefined, companyId: string, path: string) {
  const res = await fetch(`${baseUrl}/api/companies/${companyId}/${path}`, {
    headers: apiKey ? { authorization: `Bearer ${apiKey}` } : undefined,
  });
  if (!res.ok) {
    const body = await res.text();
    throw new Error(`Pre-check failed: ${res.status} ${body}`);
  }
  return res;
}

function isOkResponse(res: Response): boolean {
  return res.ok;
}

try {
  const response = await fetch(url, { headers });
  const bytes = Buffer.from(await response.arrayBuffer());
  if (!response.ok) throw new Error(`API error ${response.status}: ${bytes.toString("utf8")}`);
} catch (err) {
  if (err instanceof Error && err.message.startsWith("API error 401")) {
    // refresh API key, then retry once
  } else if (err instanceof Error && err.message.startsWith("API error 5")) {
    // transient; retry with backoff
  } else {
    throw err;
  }
}

When it happens

Trigger: Any non-2xx response from the company export endpoint: 401/403 (auth), 404 (wrong company or path), 500 (server error), or network-layer non-OK. Uses raw fetch, not the API client, so auth comes from ctx.api.apiKey as a Bearer header.

Common situations: Missing or expired API key, wrong --company-id, base URL pointing at the wrong host, or a server-side failure during export.

Related errors

• Request failed: ${response.status}
• CLI auth challenge was cancelled.
• CLI auth challenge expired before approval.
• Environment variable ${envName} is empty or not set.
• Challenge secret is required. Pass --token or --token-env.

AI-assisted analysis of paperclipai/paperclip@67001ec6eb (2026-08-12). Data as JSON: /api/errors/09c0b2f10f6b2328. Report an issue: GitHub.