Reference

Errors

Every failure has the same envelope. The code is stable; the message is for people.

On this page

The envelope#

Every failure on /api/v1 has the same body, whatever the status.

JSON

{
  "error": {
    "id": "err_3f9a1c07b2de",
    "code": "budget_exhausted",
    "message": "This agent has used 5 of 5 credits today. It resets at 00:00 UTC. Maya Chen can raise the cap in Developer.",
    "resetsAt": "2026-10-07T00:00:00Z",
    "askAHuman": "Maya Chen can raise the cap in Developer."
  }
}

A 429 for a spent daily cap. The Retry-After header carries the seconds until reset.

Field	Meaning
`id`	`err_` and 12 hex characters. Quote it when you report a problem.
`code`	A stable string. Branch on this, not on the message or the status alone.
`message`	A sentence for people. It can change.
`field`	Present when one field of the request is to blame.
anything else	Extra keys for this code, flattened into the object: `resetsAt`, `askAHuman`, `deletedAt`, `restoreUntil`.

A body that cannot be decoded is a 400 validation. A framework error with no code of its own becomes unauthenticated, forbidden, not_found, validation or conflict for 401, 403, 404, 400 and 409, and http_<status> for anything else. Anything unclassified is a 500 internal.

Three other shapes#

OAuth endpoints answer { "error": "invalid_grant", "error_description": "…" } as OAuth requires.
MCP answers with JSON-RPC. A protocol fault is a JSON-RPC error object with one of the codes -32700, -32600, -32601, -32602 or -32603. A tool that fails is a successful JSON-RPC result with isError: true and structuredContent: { "error": "<code>", "message": … }. See Connect an agent.
The event stream reports a failed step as an event of kind: "failed" in the stream, not as an HTTP error.

Codes#

Only codes a key, an agent or an unauthenticated caller can meet on the documented routes are listed. A code that belongs to a screen only a person uses is not.

Credentials and access#

Code	Status	Meaning and what to do
`invalid_key`	401	The token is unknown, revoked, or has the wrong prefix for the path. A key (`bz_live_`) only works under `/api/v1`, an agent token (`bz_mcp_live_`) only under `/mcp`. The response carries a `WWW-Authenticate` challenge.
`key_not_allowed`	403	The route is not one of the 36 a key may call. It stays with a person. No scope changes this.
`scope_missing`	403	The credential does not carry the scope the route needs. Make a new credential; scopes cannot be edited.
`human_only`	403	The action needs a signed-in person.
`forbidden`	403	The scope is right, but the role of the person who created the credential does not allow it.
`origin_refused`	403	MCP only. A request carried an `Origin` header that is not the app’s own origin.
`site_mismatch`	403	MCP only. The `?site=` on the address names a different site from the one the agent is bound to.
`rate_limited`	429	More than 60 requests a minute for this key or agent, or one of the narrower limits on Rate limits and caps. Wait for `Retry-After`.
`budget_exhausted`	429	The key or agent has used its daily credit cap. The body has `resetsAt` and `askAHuman`; `Retry-After` is the seconds until 00:00 UTC.
`workspace_deleted`	410	The workspace was deleted. The body has `deletedAt` and `restoreUntil`.
`workspace_paused`	409	Brenzuri has paused the workspace. Nothing is started or changed until it is resumed.
`switch_on`	409	Brenzuri paused this kind of work. Nothing was started and no credits were held. The message is generic for a key or an agent.

Requests and the engine#

Code	Status	Meaning and what to do
`validation`	400 · 422	A field is wrong or the body could not be read. `field` names it when one field is to blame.
`not_found`	404	No such route, article, brief, site, job or export, or one this credential cannot see. A site-bound credential gets this for anything on another site.
`not_built_yet`	501	The feature is not built on this deployment: a PDF export when no renderer is configured.
`invalid_url`	400	The address is not a full URL starting with `https://`.
`unsafe_url`	400	The address points at a private network and is not fetched. Redirects are checked too.
`unsupported_pdf`	415	A column source that is a PDF. Paste the page or a note instead.
`internal`	500	Something failed on the engine. Quote `error.id` when you report it.
`provider_unavailable`	503	The model provider is busy. `Retry-After: 60`. Nothing changed.
`not_configured`	500	The engine has no model gateway configured for this step.

Credits#

Code	Status	Meaning and what to do
`insufficient_credits`	402	The workspace does not have enough credits, or its trial has ended. For a key or an agent the message carries no numbers.
`plan_limit`	409	A plan limit is reached, such as long articles in the month, or connected agents. The message is generic for a key or an agent.

Articles, sites and columns#

Code	Status	Meaning and what to do
`article_exists`	409	The site already has an article on this subject. The message names up to three. Send `alsoNew: true`, or `supersedes` with the id of the one to replace.
`article_archived`	409	The article is archived and cannot be changed.
`article_generating`	409	The article is still being written, or one of its language versions or a job that adds languages is. Retry when it has finished.
`invalid_language`	422	A `language` the engine cannot write: a code in a `+` list that is not one of the 22 supported, is listed twice or is empty, a value with a space in it, or, when adding languages to an article, a code that is empty, the article’s own, already a version of it, or an article whose own language is not one of the 22. `field` is `language` or `languages`.
`not_primary`	422	Languages are added to the article written from the brief, not to one of its language versions. Use its `primaryArticleId`.
`still_writing`	409	The article is still being written; the version cannot be changed yet.
`article_changed`	409	The article moved on since `expectedVersion`. Nothing changed. Read it again.
`site_not_ready`	409	The site is paused, still being read, or failed to read.
`site_reading`	409	A read of this site is already running.
`column_not_ready`	409	The column has fewer than 3 independent origins. Send `flagged: true` to write it anyway, with its single-source claims marked.
`column_written`	409	That column has already been written.
`source_exists`	409	That source is already on the column, or already an origin.
`too_many_sources`	409	A column holds at most 10 of your sources.

Edits#

Code	Status	Meaning and what to do
`source_unreadable`	422	The page could not be fetched or read. Nothing was added.
`unreadable_source`	422	A column source could not be read, or has no readable text.
`source_does_not_support`	422	The page was read but does not carry the claim. Nothing was added.
`grouping_unavailable`	503	The service that groups sources by origin did not answer, so independence could not be checked. Retry.
`rewrite_added_claims`	422	The rewrite introduced a statement the sources do not carry. Nothing changed.
`block_not_rewritable`	422	A heading has no claims to rewrite from.
`table_row_not_editable`	422	A table row cannot be edited this way yet.
`wrong_unit_kind`	422	That part of the text is edited with a different route.
`unsourced_statement`	422	The edit says something the sources do not carry. A key or an agent cannot add it to a title, deck or heading.
`sources_not_checked`	422	The sources could not be checked, so a key or an agent cannot make this edit now.
`text_required`	400	The edit has no text.
`text_too_long`	400	The text is over the limit for this part: 200 characters for a title or heading, 400 for a deck, 500 for a table cell, 4,000 for other text.
`cells_mismatch`	422	The number of cells does not match the table’s columns.
`invalid_structure_edit`	400	The structure operation is not one the route takes.
`last_paragraph`	422	An article keeps at least one paragraph.
`paragraph_first`	422	An article opens with a paragraph, not a heading, list or table.
`flagged_removal_needs_person`	409	The text carries a flagged claim. A key or an agent can add a source or leave it; removing it stays with a person.

Jobs#

Code	Status	Meaning and what to do
`job_not_paused`	409	The job is running, so there is nothing to retry or skip.
`step_mismatch`	409	The failed step is not the one named in the path.
`job_settled`	409	The job has already finished.
`step_not_optional`	400	Only an optional step (`seo`, `illustrate`, or a language version step such as `write-es`) can be skipped. The others change what the article claims about its sources.

Export and delivery#

Code	Status	Meaning and what to do
`approval_required`	409	The workspace requires an editor’s approval before export and the current version is not approved.
`export_blocked_flagged`	409	The workspace blocks export while any claim is flagged.
`report_too_large`	422	The PDF would be over 2 MB of layout. Export Markdown instead.
`render_unavailable`	503	The PDF renderer is unavailable or answered unexpectedly. Retry, or export Markdown.
`connection_in_use`	409	The connection delivers for another site only.
`no_connection`	409	MCP only, `export.render` with `wordpress`. The site has no WordPress connection.

Illustrations#

Code	Status	Meaning and what to do
`illustrations_off`	503	Illustrations are not switched on for this deployment.
`illustration_regenerating`	409	A new illustration is already being made for this article.
`no_illustration`	409	Regenerating an illustration of an article that has never had one. Nothing is made.
`beat_article`	409	A Beat’s article keeps the illustration it was written with.

Other#

Code	Status	Meaning and what to do
`conflict`	409	A conflict the engine did not give a more specific code to.
`unauthenticated`	401	Session routes only. A bearer token that fails gets `invalid_key`.
`http_<status>`	other	An HTTP error from the framework that has no code of its own. The number is the HTTP status.