Errors

Every non-2xx answer throws a ConcatflowError with its status, code and body.

import { ConcatflowError } from "@concatflow/node";

try {
  await concatflow.sessions.create({ assistantId, partitions });
} catch (err) {
  if (err instanceof ConcatflowError && err.code === "partition_keys_mismatch") {
    console.error("Expected keys:", (err.body as any).detail.expected);
  }
  throw err;
}

ConcatflowError

name · "ConcatflowError"

message · string

Concatflow API <status>: <reason>. Never contains your API key.

status · number

The HTTP status.

code · string | undefined

The machine-readable reason, when the API gives one. Branch on this, not on message.

body · unknown

The parsed response body, as JSON when it is JSON, as text otherwise.

API errors

Status	code	Meaning	What to do
400	invalid_body	Malformed request: assistantId is not a UUID, or a partition is missing.	Fix the call.
401	invalid_api_key	The key is wrong or revoked.	Check CONCATFLOW_API_KEY.
402		Not enough credits.	Top up your workspace.
403	partition_keys_mismatch	Partition keys are not exactly the assistant’s. body.detail.expected lists them.	Send exactly those keys.
404		Unknown assistant, or one from another workspace.	Check the assistant ID and that the key belongs to its workspace.
409	not_published	The assistant is not published.	Publish it.
409	door_closed	The per-user door is off.	Turn it on in Doors.
409	isolation_unsigned	The isolation is not signed.	Sign it in Isolation.
422	bad_partition	The partition of conversations.list or erase cannot be read.	Send at least one key with a value.
422		A partition key is over 63 characters, or a value over 200.	Shorten it.
502	backend_unreachable	Concatflow could not reach its API.	Retry with backoff.

Validation errors

Some mistakes never reach the network. They throw a plain TypeError or Error, not a ConcatflowError:

Thrown	When
Error	apiKey does not start with lyra_sk_, or the client runs in a browser.
TypeError	assistantId is empty, partitions is empty or not an object, a value is empty or not a finite number.
TypeError	A partition key or value contains , or = (conversations.list and erase).

Network errors

If fetch itself fails (DNS, connection refused), its own error is thrown, not a ConcatflowError.