Errors

A successful response has status: "success" and a data object. A failure has status: "error" and an error object.

{
  "status": "error",
  "error": {
    "message": "Unsupported rail 'foo'",
    "code": "unsupported_rail"
  }
}

string

required

Always error on failure.

string

required

Human-readable explanation. Safe to show a developer; do not parse it.

string

required

Stable machine-readable code. Branch on this.

array

Optional extra context — validation messages, and so on.

Every code is lower_snake_case.

HTTP status codes

Status	Meaning
`200`	Success.
`201`	Created.
`202`	Accepted — a run, an outcome, or a confirmation.
`400`	Bad request — missing or illegal parameters.
`401`	Missing or invalid credential.
`402`	Out of credits.
`403`	Authenticated, but not allowed.
`404`	The referenced resource does not exist.
`409`	Conflict — the resource already exists.
`413`	Payload too large.
`422`	Understood, but cannot be processed.
`429`	Rate limited.
`500`	Something broke on our side.
`502`	An upstream provider failed.
`503`	A capability is not configured on this deployment, or an upstream provider is temporarily unavailable.

Any endpoint

These come from the platform rather than a product, and can appear anywhere.

Code	Status	When
`missing_parameter`	`400`	A required field was omitted.
`bad_request`	`400`	The request is malformed in a way no other code describes.
`invalid_parameter`	`400`	A parameter is present but malformed.
`subject_required`	`400`	The resource is partitioned by subject and the call named none. Send `Patchwork-Subject`, or use a session token.
`invalid_subject`	`400`	The subject is unusable — empty, over 255 bytes, or carrying control characters or leading/trailing whitespace. Subjects are compared exactly and never trimmed, so a stray space would silently become a second partition.
`unauthorized`	`401`	Missing or invalid API key or session token.
`insufficient_credits`	`402`	The workspace balance is empty. Top up and retry.
`forbidden`	`403`	Authenticated, but not allowed on this resource.
`email_not_verified`	`403`	The account’s address is unconfirmed. Issuing credentials, publishing, inviting and spending all require a verified address.
`not_found`	`404`	The referenced resource does not exist.
`conflict`	`409`	The resource already exists.
`validation_error`	`422`	A field was present but failed validation. `details` carries the messages.
`unprocessable_entity`	`422`	Understood, but cannot be processed, with no more specific code.
`idempotency_in_flight`	`409`	A request with this `Idempotency-Key` is still running. Honour `Retry-After` and retry.
`idempotency_key_reuse`	`422`	This `Idempotency-Key` was already used with a different body. Use a new key.
`rate_limited`	`429`	Burst or sustained limit hit. Honour `Retry-After`.
`internal_server_error`	`500`	Unexpected failure on our side. Safe to retry.

Identify

Code	Status	When
`unsupported_rail`	`400`	`rail` is not one Identify supports.
`invalid_code`	`400`	The identifier failed validation — malformed NUBAN, bad IBAN check digits, and so on.
`provider_unavailable`	`503`	We could not reach the institution data behind this rail. The identifier is not wrong and the result is not `not_found` — the lookup simply did not happen. Honour `Retry-After` and retry.

provider_unavailable and not_found mean different things, and it matters which one you act on. not_found is an answer: we looked, and no institution matches that code. provider_unavailable is the absence of an answer. Never treat it as a failed verification or mark an account unreachable on it — retry instead.

Extract

Code	Status	When
`unknown_template`	`400`	`template` does not name a schema type in this workspace.
`no_schema_types`	`400`	`template` is `auto` but the workspace has no schema types to match against.
`unsupported_media_type`	`400`	`document.media_type` is not supported.
`document_too_large`	`400`	The document is over 10 MiB.
`too_many_pages`	`400`	The PDF has more than 15 pages.
`invalid_document`	`400`	The bytes are empty, not valid base64, or do not match `media_type`.
`invalid_schema`	`400`	The schema is not a supported subset — bad type, banned keyword, too deep, or over 40 fields.

Files

Code	Status	When
`file_too_large`	`413`	Over the single-shot limit. Use the chunked flow.
`invalid_file`	`400`	The upload is empty, malformed, or of a media type we do not accept.
`unknown_file`	`400`	The `file_…` id does not name a file in this workspace.
`invalid_segment`	`422`	A chunk index is out of range, or its size is not what was declared.
`upload_not_open`	`409`	The chunked upload was already finalized.
`incomplete_upload`	`422`	Completion was requested with segments still missing.
`attachment_too_large`	`400`	An attachment exceeds the per-message limit.
`too_many_attachments`	`400`	More attachments than a message allows.

Loom — threads and messages

Code	Status	When
`agent_required`	`400`	A thread was created without an `agent`.
`unknown_agent`	`404`	The `agent_…` id does not name a published agent in this workspace.
`connection_required`	`422`	The agent has unpinned customer tools and no connection was named.
`unknown_connection`	`400`	The named connection does not exist in this workspace.
`connection_locked`	`409`	A thread’s connection cannot be changed once its first run has started.
`connection_mismatch`	`400`	The named connection disagrees with the one the thread is pinned to.
`awaiting_confirmation`	`422`	A message was posted while a write was waiting for approval. Resolve it first.

Loom — outcomes and confirmations

Code	Status	When
`unknown_action`	`404`	The outcome names a tool call that is not a pending proposed action.
`not_awaiting_outcome`	`422`	The run is not waiting for an outcome.
`invalid_state`	`422`	Outcome `state` is not `occurred` or `failed`.
`unknown_confirmation`	`404`	The confirmation names a call that is not held at a gate, or already resolved.
`not_awaiting_confirmation`	`422`	The run is not paused at a gate.
`invalid_decision`	`422`	Confirmation `decision` is not `approve` or `reject`.

Voice

Code	Status	When
`voice_unavailable`	`503`	No voice provider is configured. A normal deployment state — hide the affordance rather than showing an error.
`voice_provider_error`	`502`	The provider failed. Retrying is reasonable.
`voice_invalid_format`	`422`	`format` is not `markdown` or `plain`.
`voice_empty_text`	`422`	Nothing is left to speak after rendering.

See the Voice guide for how these surface through the React SDK — it swallows voice_empty_text deliberately.

OAuth and MCP

The OAuth endpoints behind MCP export return the codes RFC 6749 and RFC 7591 define — invalid_request, invalid_client, invalid_grant, unsupported_grant_type, access_denied, invalid_client_metadata — in the shapes those specs require, not this envelope. Your client’s OAuth library will expect exactly that.

Core

Conversations

Configuration

Delivery

MCP

Workbench

HTTP status codes

Any endpoint

Identify

Extract

Files

Loom — threads and messages

Loom — outcomes and confirmations

Voice

OAuth and MCP

​HTTP status codes

​Any endpoint

​Identify

​Extract

​Files

​Loom — threads and messages

​Loom — outcomes and confirmations

​Voice

​OAuth and MCP

HTTP status codes

Any endpoint

Identify

Extract

Files

Loom — threads and messages

Loom — outcomes and confirmations

Voice

OAuth and MCP