> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.cessy.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.cessy.ai/_mcp/server.

# Errors

> Understand Cessy error statuses, response envelopes, command failures, policy failures, webhook failures, and troubleshooting order.

Cessy errors should tell you which layer failed: auth, permission, validation, command logic, projection read, policy execution, webhook handling, adapter call, or platform operation.

## Common statuses

| Status | Meaning                                                                                   |
| ------ | ----------------------------------------------------------------------------------------- |
| `400`  | Invalid request shape, invalid query, or failed validation.                               |
| `401`  | Missing or invalid authentication.                                                        |
| `403`  | Authenticated caller lacks required scope, role, attribute, or app access.                |
| `404`  | Tenant, app, environment, command, projection, or resource not found.                     |
| `409`  | Business conflict, concurrency conflict, duplicate handling, or invalid state transition. |
| `422`  | Semantically invalid command or payload.                                                  |
| `500`  | Unexpected platform or integration failure.                                               |

## Command failures

Command failures usually mean the business decision was rejected. Inspect:

* command input
* actor and permissions
* loaded decision state
* validation error
* emitted or missing events

## Policy and adapter failures

Policy failures happen after an event or trigger. Inspect the policy execution with `get_execution`. Adapter diagnostics identify the operation, substitution/login/call phase, safe method/path, HTTP status, attempts, and retry/refresh decisions. They are retained for non-success responses even when policy code handles the result and the policy completes successfully. If the policy also fails, use `get_error_context` for the corresponding Error Log entry. Diagnostics are bounded and redact credentials, auth headers, cookies, query strings, and full upstream URLs.

## Thrown worker diagnostics

For a `worker_error`, inspect `get_error_context` and the linked policy execution
with `get_execution`. Thrown failures carry a bounded `failureDiagnostic`:
`version`, worker `phase` (`module_load`, `handler`, or `transport`), category,
recognized code and error class, and up to four causes. Exact SMTP phase and
failure response numbers are retained when supplied as structured fields.
Categories distinguish dependency loading, configuration, connection, TLS,
authentication, provider rejection, platform failure, and unknown causes.
A code or phase is reported evidence; it is not a proof of provider state.

Raw exception text, stack, worker logs, upstream responses, recipient addresses,
message bodies and arbitrary error properties are omitted. Unrecognized symbols
stay unknown. Existing safe adapter diagnostics and policy-returned failure
command details remain separate contracts. Historical failures without a receipt
say that diagnostics are unavailable in the original evidence; inspecting them
does not recreate the missing cause.

An exact `dpe1_...` durable-child handle resolves to its canonical work and child
identity, current disposition and retained failure attempt. A later successful
reconciliation does not erase that receipt. Scope checks still require the
correct tenant, app and Workspace. Unavailable storage is inconclusive.

Durable publication receipts cover platform publications. Zero publications or
zero emitted events do **not** prove that a worker made no external call or that
a provider accepted no partial effect. An entered arbitrary handler with no
instrumented external receipt requires external verification before the existing
fenced reconciliation procedure can be used. Do not replay the source command,
send a test email to a real recipient, or infer a common cause across unrelated
worker failures.

## Webhook failures

Webhook failures often come from auth, payload shape, guard expressions, mapping, or downstream command validation. Keep sender request ids in logs when possible.

## Troubleshooting order

1. Confirm tenant, app, and environment.
2. Confirm auth and scopes.
3. Check permissions for the actor.
4. Validate request shape against generated contract.
5. Inspect Activity and policy executions for command, event, policy, webhook, and adapter evidence.
6. Check Data Explorer for projection state.
7. Inspect error logs for platform-level failures.