Errors

Every API response — success or failure — uses one envelope. Failures carry a stable machine-readable code, a human-readable message, and the request ID. Quote outcomes such as requires_input or failed are not errors: they are successful responses with an unpriced Receipt.

Envelope shape

Success (200 or 201):

{ "data": { "…": "…" }, "requestId": "req_…" }

Failure:

{
  "error": {
    "code": "invalid_quote_request",
    "message": "A Business, offering, and factor selections are required.",
    "requestId": "req_…",
    "details": { "fields": { "offeringId": ["Required"] } }
  }
}

Field	Description
`code`	Stable, machine-readable error code. Program against this, not the message.
`message`	Human-readable explanation.
`requestId`	Unique request identifier, also mirrored in the `x-request-id` response header.
`details`	Optional structured context — for validation failures, `details.fields` maps field names to issues.

Error codes

Quote routes

HTTP	Code	When
422	`invalid_quote_request`	Body failed schema validation (missing `offeringId`, bad UUID, unknown keys). See `details.fields`.
404	`quote_scope_not_found`	The Business, Book, or Environment scope does not exist for this credential (API-key and member routes).
404	`quote_surface_unavailable`	Public route only: the Business or its connection is inactive, or nothing is published Live.
404	`quote_not_found`	Retrieval: no Quote with that ID is visible to this credential or surface. On the public route, member and API-key Quotes are invisible to anonymous reads by design.
409	`idempotency_conflict`	The idempotency key was already used with a different payload.
429	`rate_limited`	Anonymous public route only: the Business exceeded 120 quote creates per minute. Back off and retry; the request was not processed.
401	`invalid_api_key`	Missing, malformed, unknown, or revoked bearer key on the headless routes.
503	`quote_failed`	The data plane could not resolve the request. Retry; use `requestId` when contacting support.

Book authoring and publication routes

HTTP	Code	When
422	`invalid_book_draft`	The draft failed compilation at publish time; `details.issues` lists every validation issue.
409	`draft_revision_conflict`	`expectedRevision` is stale — another actor saved first. Reload the draft instead of overwriting.

Business membership and branding routes

HTTP	Code	When
401	`unauthorized`	No authenticated session on a member route.
403	`not_business_owner`	Member administration requires an active Business Owner membership.
409	`last_owner_protected`	The change would demote or remove the last active Owner. Promote another Owner first.
404	`business_membership_not_found`	The caller is not an active member of this Business.
422	`invalid_member_request`	The role is not one of `owner`, `editor`, `viewer`.
422	`invalid_branding`	Branding failed validation (non-HTTPS URL, bad color, over-length name, unknown keys).
403	`branding_forbidden`	The caller may not edit this connection’s branding (for example, a managed Business’s portal user).

API key, webhook, and log routes (Workspace management)

These routes authenticate the Workspace session and authorize against Workspace roles.

HTTP	Code	When
401	`unauthorized`	No authenticated session.
403	`forbidden`	Your Workspace role lacks the required permission (for example `webhooks:manage`, `logs:read`, `api_keys:create`).
403	`active_workspace_required`	No active Workspace is selected for the session.
422	`invalid_request`	Body or query failed validation (bad UUID, non-HTTPS webhook URL, unknown keys). See `details.fields`.
404	`environment_not_found`	The Project or Environment does not exist in the active Workspace.
404	`api_key_not_found`	The API key does not exist in the active Workspace.
409	`api_key_not_active`	Rotation target is revoked or otherwise not active.
404	`webhook_endpoint_not_found`	The webhook endpoint does not exist in the active Workspace.
404	`webhook_delivery_not_found`	The webhook delivery does not exist in the active Workspace.
404	`workspace_not_found`	The request-log query could not resolve the active Workspace.
404	`quote_trace_not_found`	No Quote Intent with that ID is visible to the active Workspace.

Quote outcomes are not errors

A created Quote always returns 201 with a Receipt, even when the Receipt is unpriced:

Receipt outcome	Meaning	How to handle
`succeeded`	Priced; full computation attached.	Render line items, total, and conditions.
`requires_input`	Inputs are missing.	Collect the `missingInputs` paths and resubmit with a new idempotency key.
`failed`	Unpriced (`unknown_offering`, `unknown_factor`, `unknown_factor_option`, `no_published_version`, or an engine code).	Read `failure.code`; route to manual handling or fix the request.

Handle outcomes in your integration logic and reserve error handling for the envelope above.

The request ID

Every response includes x-request-id. Quote creates also echo it as the Intent and Receipt requestCorrelationId, so a customer-facing Quote can always be traced back to the exact HTTP request. Include it in support reports.

Start here

Core concepts

Distribution

Operations

Envelope shape

Error codes

Quote routes

Book authoring and publication routes

Business membership and branding routes

API key, webhook, and log routes (Workspace management)

Quote outcomes are not errors

The request ID

​Envelope shape

​Error codes

​Quote routes

​Book authoring and publication routes

​Business membership and branding routes

​API key, webhook, and log routes (Workspace management)

​Quote outcomes are not errors

​The request ID

Envelope shape

Error codes

Quote routes

Book authoring and publication routes

Business membership and branding routes

API key, webhook, and log routes (Workspace management)

Quote outcomes are not errors

The request ID