Errors

Every error from the Driftless API (whether you reach it through the CLI, the MCP server, or directly) comes back as the same JSON envelope. An agent should branch on the machine-readable code, not parse the human message.

The envelope

{
  "statusCode": 403,
  "code": "MISSING_HUMAN_IDENTITY",
  "message": "Merging into Knowledge requires owner/admin authority: your own session or an owned owner/admin key (an agent acting on your explicit request). A faceless agent (ownerless key / OAuth) cannot merge.",
  "request_id": "a1b2c3d4",
  "retryable": false,
  "endpoint": "POST /api/v1/workspaces/acme/topics/auth-flow/approve"
}

Field	Meaning
`statusCode`	HTTP status.
`code`	Stable, machine-readable error code (this list is additive-only).
`message`	Human-readable, actionable. Tells you how to fix it. May change; don’t match on it.
`request_id`	Correlation id. Quote it when reporting an issue.
`retryable`	`true` only for genuine transient failures (5xx). A `4xx` is a definitive answer, so retrying won’t help.
`endpoint`	The method + path that produced the error.

retryable is honest: the CLI auto-retries a GET once on a transient failure but never re-sends a write, and never retries a 4xx. If you build your own client, do the same.

Why a `code` at all

Input that’s wrong shouldn’t reach the agent as an opaque 500. Two layers guarantee that:

Validation rejects a bad enum (status, visibility) with a field-level 400 before it touches the database.
A Postgres-error translator catches any constraint violation that slips through and turns it into a coded 4xx, never a generic 500.

After those two, a 500 means what it should: a real bug or an outage. That’s also the only time retryable is true.

Code catalog

Validation & input

`code`	Status	When
`VALIDATION_FAILED`	422 / 400	A request body field failed validation (e.g. `status must be one of: draft, proposed, reviewed, …`).
`BAD_REQUEST`	400	A generic bad request with no more specific code.
`INVALID_VALUE`	400	A value violates a database CHECK constraint.
`INVALID_ID`	400	A path/body identifier is not a valid UUID.
`REQUIRED_FIELD`	400	A required field was missing.
`FK_VIOLATION`	400	References a record that does not exist.
`SECRET_DETECTED`	400	A topic field looked like a credential (API key, token, private key) and the write was blocked. Remove it, or set `allow_secrets: true` (CLI `--allow-secrets`) to override. The error masks the match; it never echoes the secret.

Access & identity

`code`	Status	When
`UNAUTHORIZED`	401	Missing or invalid API key / token. → `driftless login --key <key>`.
`FORBIDDEN`	403	Authenticated, but not allowed.
`MISSING_HUMAN_IDENTITY`	403	A faceless principal (an ownerless key, or an OAuth token with no owner/admin behind it) tried to merge into Knowledge. Re-issue the key from the dashboard so it carries your identity, or run the merge under an owner/admin.
`INSUFFICIENT_ROLE`	403	You lack the workspace role for this action: only an owner/admin can approve. Ask one to promote you in Settings → Members.
`NOT_FOUND`	404	The resource doesn’t exist (or another member’s private draft you can’t see, so we return 404, never 403).
`METHOD_NOT_ALLOWED`	405	The path is real but the verb isn’t — carries an RFC 9110 `Allow` header naming the methods that do work. Market Data’s HTTP surface returns this instead of a bare 404 for a wrong-verb request.

Governance & conflicts

`code`	Status	When
`DUPLICATE`	409	A record with these values already exists.
`DUPLICATE_TOPIC`	409	A topic with that slug already exists in the workspace.
`VERSION_CONFLICT`	409	`expected_version` didn’t match: someone wrote since you read. Re-read and retry.
`CONFLICT`	409	A generic state conflict.
`PROTECTED_RESOURCE`	403	A protected/default resource can’t be modified or deleted.
`RATE_LIMITED`	429	Too many requests. Back off.

Commercial allowance

`code`	Status	When
`COMMERCIAL_CALL_LIMIT_REACHED`	402	The workspace used its included top-level commercial requests for the month.
`COMMERCIAL_CREDITS_EXHAUSTED`	402	No commercial-intelligence credits remain in the current month.
`COMMERCIAL_CREDITS_INSUFFICIENT`	402	The requested result count is larger than the per-request or remaining-credit allowance.

These errors include the current usage snapshot and an actionable next_action for contacting sales. They are definitive (retryable: false).

Server

`code`	Status	When
`INTERNAL`	500	An unexpected failure. `retryable: true`. Quote `request_id` if it persists.

Observability

Every captured error is also emitted to PostHog (request_failed server-side, command_failed from the CLI) with code, status_code, and endpoint as properties, so the error surface is one queryable map, sliceable by type and endpoint rather than free-text. The exception text itself never leaves the log — join on request_id.

Get started

Connect

Concepts

Work & collaborate

Guides

Agents

MCP reference

CLI reference

API reference

Platform

The envelope

Why a `code` at all

Code catalog

Validation & input

Access & identity

Governance & conflicts

Commercial allowance

Server

Observability

​The envelope

​Why a code at all

​Code catalog

​Validation & input

​Access & identity

​Governance & conflicts

​Commercial allowance

​Server

​Observability

The envelope

Why a `code` at all

Code catalog

Validation & input

Access & identity

Governance & conflicts

Commercial allowance

Server

Observability