Error handling

Custom blocks are in private alpha:

Do not discuss publicly or share with anyone outside your workspace.
Access must be enabled per workspace. Installing the SDK does not grant access.
These APIs may experience breaking changes without notice.

initCustomBlock() rejects when initialization fails. Data and page operations return errors in their results.

The error shape

Every error, thrown or returned, carries the same three fields:

Field	Description
`code`	A stable string identifying what went wrong. Branch on this.
`message`	A human-readable description. Do not parse it.
`isRetryable`	Whether retrying the same operation could succeed.

Branch on code and use message for display or logging only — messages are not part of the contract and can change between versions.

Handling operation errors

const result = await pages.update({ pageId, properties })

if (result.status === "error") {
	if (result.error.isRetryable) {
		return scheduleRetry()
	}

	reportToUser(result.error.message)
	return
}

render(result.page)

isRetryable is the SDK telling you whether a retry is meaningful. A transient host failure is retryable; a permission denial or an invalid property value is not, and retrying it only burns time. Do not retry on a non-retryable code. Common non-retryable causes across the page and data source APIs:

The viewing user lacks access to the page or data source.
A property key is not declared in the block’s manifest, or its ID does not match the bound data source.
A property value does not match its property’s type.
A data source key is not declared, or is declared but not bound.
The requested parent is not a valid parent for a new page.

Handling initialization errors

NotionCustomBlock renders errorFallback instead of its children when initialization fails, except for NotInIframeError as described below:

<NotionCustomBlock
	errorFallback={(error) => <BlockFailed error={error} />}
>
	<App />
</NotionCustomBlock>

For custom initialization, read the error from useCustomBlockInit() or catch the rejection from initCustomBlock(). Both APIs report a CustomBlockInitializationError with the fields listed above.

`NotInIframeError`

This error has code not_in_iframe and is never retryable. It means you opened the block directly in a browser tab without a host to supply real context. NotionCustomBlock handles this error by rendering its children with placeholder context and a standalone preview warning. It does not render errorFallback. Use ntn workers customblocks dev to test host behavior and data source bindings.

Other initialization codes

Initialization codes describe what the host could not provide:

Cause	Codes
Manifest problems	`manifest_unavailable`, `manifest_invalid`
Protocol mismatch	`invalid_protocol_version`, `unsupported_protocol_version`
Missing context	`context_unavailable`, `current_user_unavailable`
Data source binding	`missing_data_source_binding`, `data_source_unavailable`, `invalid_init_bindings`
Property binding	`missing_property_binding`, `invalid_property_binding`
Environment	`not_in_iframe`, `init_timeout`

A protocol mismatch means the installed SDK and the host disagree on the bridge version. Because custom blocks are pre-1.0, the fix is generally to upgrade @notionhq/custom-blocks and redeploy. Binding codes mean the block declared a data source or property that the block’s configuration in Notion does not satisfy. Either the block instance needs to be reconfigured, or the manifest declares something the bound data source does not have.

Designing for failure

A block runs inside someone else’s page, against a data source you did not choose, for a user whose permissions you do not control. Assume every read can come back empty and every write can be refused. Render something useful when a data source is empty rather than treating it as an error, keep the failure visible inside the block rather than silently swallowing it, and never assume a write succeeded because it was accepted.

Error code reference

The exported error code unions are exhaustive per API, and they track the SDK version, so the full list ships with the package rather than here. See node_modules/@notionhq/custom-blocks/docs/errors.md.

Get started

Guides

Workers SDK reference

Custom blocks SDK reference

CLI reference

The error shape

Handling operation errors

Handling initialization errors

`NotInIframeError`

Other initialization codes

Designing for failure

Error code reference

​The error shape

​Handling operation errors

​Handling initialization errors

​NotInIframeError

​Other initialization codes

​Designing for failure

​Error code reference

The error shape

Handling operation errors

Handling initialization errors

`NotInIframeError`

Other initialization codes

Designing for failure

Error code reference