> ## Documentation Index
> Fetch the complete documentation index at: https://docs.attio.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Error handling

> Return classified and unclassified errors from a workflow block

When the workflow author turns on continue on error, you can choose how each error from your block is returned:

* An **unclassified** error has no `id`. It follows the catch-all outcome, along with every other unclassified error.
* A **classified** error has an `id`, with a corresponding `<ErrorOutcome />` in the block configurator. The workflow author can then handle that error on its own outcome.

Both shapes are valid returns from [`execute`](./define-workflow-block-execute) and [`finish`](./define-workflow-block-resume-callback).

## Unclassified errors

Return an error with no `id` when you do not expect the workflow author to handle that error on its own outcome:

```ts theme={"system"}
return {
  type: "error",
  errorMessage: "Request failed: Service Unavailable",
  retryable: true,
}
```

| Field | Required | Description |
| - | - | - |
| `errorMessage` | Yes | Shown in the Attio workflows UI, to the user. |
| `retryable` | No | Set `true` for a transient error that is safe to retry, such as a rate limit or a temporary outage. Attio may retry the execution, then fail the run. Only set this when the operation is idempotent. |

When the workflow author turns on continue on error, an unclassified error follows the catch-all outcome instead of failing the run.

## Classified errors

When a specific error should have its own outcome, add an `<ErrorOutcome />` in the configurator, then return that same `id` in the error payload from `execute` (or `finish`) handlers.

### Surface the error outcome

`ErrorOutcome` comes from `Workflows.useConfigurator`, alongside `Outcome`. Render one for each error the workflow author should be able to handle:

```tsx configurator.tsx theme={"system"}
import {Workflows} from "attio/client"
import block from "./block"

export default Workflows.defineConfigurator(block, (workflowBlock) => {
  const {Outcome, ErrorOutcome} = Workflows.useConfigurator(workflowBlock)
  return (
    <>
      <Outcome id="sent" schema={null} />
      <ErrorOutcome id="recipient_not_found" label="Recipient not found" schema={null} />
    </>
  )
})
```

| Prop | Type | Description |
| - | - | - |
| `id` | `string` | Matches the `id` on the `{type: "error"}` return. Unique across this block's outcomes, including success outcomes. |
| `label` | `string` | Required. Shown in the workflow author's error-handling dropdown. |
| `schema` | `object \| null` | Shape of the error payload, built with `Workflows.OutcomeSchema.*` nodes. Pass `null` when the error carries no data. See [Outcome schema](https://docs.attio.com/sdk/workflows/outcome-schema.md). |

> [!NOTE]
>
> Rendering the `<ErrorOutcome />` only lists the error in the workflow author's error-handling
> dropdown. It does not add an outcome until the workflow author chooses to handle that
> error.

`label` is required on `ErrorOutcome`. On `Outcome` it is optional when the block has a single success outcome.

### Return the error

From `execute` or `finish`, return the same `id` with an `errorMessage` and a `data` payload:

```ts execute.ts theme={"system"}
if (response.status === 404) {
  return {
    type: "error",
    id: "recipient_not_found",
    errorMessage: "No recipient with that email",
    data: null,
  }
}
```

`id` must match an `<ErrorOutcome />` in the configurator. `data` is that outcome's payload and must match its `schema`. Pass `null` when the schema is `null`.

```ts theme={"system"}
return {
  type: "error",
  id: "rate_limited",
  errorMessage: "Too many requests",
  retryable: true,
  data: {retry_after_seconds: 30},
}
```

`retryable` is optional, as on an unclassified error. The workflow author decides whether this outcome is handled. When they handle it, the run continues down that error outcome, and downstream steps can use `data`.

## See also

* [Configurator](https://docs.attio.com/sdk/workflows/configurator.md): declaring outcomes in the workflow editor
* [Executing a step](https://docs.attio.com/sdk/workflows/define-workflow-block-execute.md): the `execute` handler
* [Finishing a deferred step](https://docs.attio.com/sdk/workflows/define-workflow-block-resume-callback.md): the `finish` handler
* [Outcome schema](https://docs.attio.com/sdk/workflows/outcome-schema.md): typing the `data` field


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.