Error codes

The webhook endpoint and the MCP server return an error code your code can act on. Automation runs record a failure kind. Errors in the app carry a code too, and the app shows the message. The codes for apps, reports and file processors are listed below, and the messages you are most likely to see are at the end of this page. For problems that come without any message, see Troubleshooting.

Webhook endpoint

A refused delivery returns a JSON body with a code, and for most codes an error message:

{ "code": "CONNECTION_PAUSED", "error": "Connection is paused" }

Only a 202 means Beetl stored the delivery. For any other status, keep the event in your sender and send it again once the cause is fixed.

Status	Code	Meaning	What to do
`400`	`INVALID_WEBHOOK_PAYLOAD`	The body is not valid JSON.	Send one valid JSON value, encoded as UTF-8.
`401`	`MISSING_TOKEN`	The request has no `Authorization: Bearer` header.	Add the connection's token as a bearer token.
`401`	`INVALID_TOKEN`	The token does not belong to this connection, or the connection was deleted.	Check that the connection ID in the URL and the token come from the same webhook.
`404`	`OUTPUT_NOT_LINKED`	The connection has no dataset to write to.	Create a new Webhook connection, which links a new dataset.
`413`	none	The body is larger than 1,000,000 bytes. This response has a plain-text body.	Send smaller events, or load large files through a File Set.
`422`	`CONNECTION_PAUSED`	The connection is paused.	Resume it from its pane on Home.
`422`	`OBJECT_STORE_NOT_CONFIGURED`	The tenant has no default object store.	A TenantAdmin adds one under Settings → Tenant → Object storage.
`422`	`TENANT_SUSPENDED`	The tenant is suspended.	Contact Beetl.
`500`	`INTERNAL_ERROR`	Beetl could not accept the delivery.	Send it again later.

See Webhook for the request format.

MCP server

HTTP errors

These come back before any JSON-RPC message is handled.

Status	Code	Meaning	What to do
`400`	none	The `MCP-Protocol-Version` header names a version Beetl does not support.	Use `2025-11-25` or `2025-06-18`.
`401`	`MISSING_API_KEY`	The request has no `X-API-Key` header.	Send your key in `X-API-Key` on every request.
`401`	`INVALID_API_KEY`	The key is unknown or was deleted.	Create a new key and update your client. See MCP setup.
`405`	none	The request used GET or DELETE.	Send every request as a POST to `/mcp`.
`500`	`INTERNAL_ERROR`	Beetl could not check the key.	Try again.

The 401 and 500 bodies are JSON with code and error, like the webhook endpoint. The 400 and 405 responses have no code.

JSON-RPC errors

A malformed message gets a JSON-RPC error object with a numeric code.

Code	Meaning	What to do
`-32600`	Invalid request: `jsonrpc` is not `"2.0"`, or `method` is missing.	Fix the message envelope.
`-32601`	Method not found.	Use `initialize`, `ping`, `tools/list` or `tools/call`.

Tool errors

A tool call that fails still returns a result, with isError: true and the reason as text. Tool errors have no code, so read the message. The ones caused by the call itself are:

Message	Meaning	What to do
`<tool> requires scope 'write'; this API key has scope 'read'.`	The tool needs a `write` key.	Use a key with the `write` scope.
`Unknown tool: <name>`	No tool has that name.	Call `tools/list` for the names your key can use.
`Invalid tools/call params: …`	The `params` object is not valid.	Send `name` and, if the tool takes any, an `arguments` object.

Other tool errors carry the reason from the tool, such as a SQL error or a missing argument. Fix the call and send it again. See Tool reference.

Automation run failures

When an automation run fails, get_automation_run returns a failure object with a kind and a message. The app shows the message on the automation's page.

Kind	Meaning	What to do
`timed_out`	The run reached its time limit before it could finish.	Narrow the instructions, or compute the heavy part in a pipeline. See Limits.
`input_required`	The run stopped to ask for input, which an automation cannot get.	Make the instructions complete enough to run without questions.
`invalid_output`	The run finished without writing a report.	Run it again. If it repeats, simplify the instructions.
`model`	The model call failed, for example because the tenant's monthly AI credits ran out.	Check AI in the tenant, then run it again. See AI in a tenant.
`tool`	A query or lookup failed, or the workspace has no dataset to query.	Read the message. Add a queryable dataset if there is none.
`runtime`	Beetl could not start or complete the run.	Run it again. If it keeps failing, contact Beetl.
`interrupted`	The service stopped before the run finished.	Run it again.

See Automations.

Apps, reports and file processors

These codes come back when you work with apps, reports and file processors in the app or in chat.

Apps

Status	Code	Meaning	What to do
`400`	`INVALID_APP_SCHEDULE`	The cron expression or time zone is invalid, or the schedule never runs.	Fix the schedule.
`400`	`UNKNOWN_APP_INPUT_QUERY`	The app has no input query by that name.	Use a name the app defines.
`400`	`APP_INPUT_NOT_VERSIONED`	The dataset is registered or external. Only materialized datasets can be bound.	Bind a materialized dataset.
`400`	`APP_INPUT_CYCLE`	The binding would make the app read its own output.	Remove the binding.
`404`	`APP_NOT_FOUND`	The app does not exist.	Check that it was not deleted.
`404`	`APP_RUN_NOT_FOUND`	The run does not exist.	Pick a run from the Runs tab.
`404`	`APP_INPUT_NOT_FOUND`	No input is bound under that alias.	Use a bound alias.
`409`	`APP_DISABLED`	The app is disabled.	Enable it first.
`409`	`APP_BUSY`	The app is processing or publishing a run.	Try again after it finishes.
`409`	`APP_RUN_NOT_PAUSED`	Only a paused run can be resumed or abandoned.	Check the run's state.
`503`	`APP_UNAVAILABLE`	This app type is unavailable.	Try again later.

Reports and automation documents

Status	Code	Meaning	What to do
`400`	`INVALID_REPORT_DOCUMENT_TAGS`	A document holds more than 20 tags.	Use fewer tags.
`404`	`REPORT_NOT_FOUND`	The report does not exist.	Check that it was not deleted.
`404`	`REPORT_RUN_NOT_FOUND`	The run does not exist.	Pick a run from the report's page.
`404`	`REPORT_DOCUMENT_NOT_FOUND`	The document does not exist.	Pick a document from the report's archive.
`404`	`REPORT_TEMPLATE_NOT_FOUND`	The template does not exist.	Choose a template from this workspace.
`404`	`REPORT_ASSET_NOT_FOUND`	The image does not exist.	Upload it again.
`404`	`AUTOMATION_DOCUMENT_NOT_FOUND`	The automation run has no PDF yet.	Choose Render PDF on the run.
`409`	`REPORT_ALREADY_EXISTS`	A report with this name exists.	Choose another name.
`409`	`REPORT_CONFLICT`	The report changed while your request was running.	Try again.
`409`	`REPORT_ALREADY_RUNNING`	A run is in progress.	Wait for it to finish.
`409`	`REPORT_TEMPLATE_LIMIT`	The workspace holds 50 templates.	Delete one you no longer use.
`409`	`REPORT_ASSET_LIMIT`	The report or template already has 20 images.	Remove one first.
`409`	`AUTOMATION_RUN_NOT_COMPLETED`	Only a completed run can render its document.	Wait for the run, or run it again.
`409`	`AUTOMATION_HAS_NO_TEMPLATE`	The automation has no report template.	Choose a template in its definition.
`413`	`REPORT_ASSET_TOO_LARGE`	The image is over 2 MiB.	Use a smaller image.
`422`	`REPORT_INVALID`	The SQL or the layout does not work.	Read the diagnostics, which name the failing binding.
`422`	`INVALID_REPORT_ASSET`	The image is not a valid PNG, JPEG, WebP or SVG file.	Upload a valid image in one of those formats.
`422`	`OBJECT_STORE_NOT_CONFIGURED`	The tenant has no object store.	A TenantAdmin adds one under Settings → Tenant → Object storage.
`503`	`NO_RUNNER_AVAILABLE`	Nothing was free to render the report.	Try again shortly.

Saving an automation with a template name that does not exist returns INVALID_AUTOMATION, with REPORT_TEMPLATE_NOT_FOUND on the template field.

See Apps, Reports and Automations.

File processors and documents

Status	Code	Meaning	What to do
`400`	`INVALID_FILE_PROCESSOR_NAME`	The processor name is not valid.	Enter a different name.
`400`	`UNSUPPORTED_DOCUMENT_FORMAT`	The processor does not accept this file format. A Spreadsheet processor accepts only `.xlsx`.	Upload a supported format, or add the file to a different processor.
`400`	`INVALID_DOCUMENT_CORRECTION`	The corrected values do not match the processor's fields.	Fix the highlighted fields and save again.
`404`	`FILE_PROCESSOR_NOT_FOUND`	The processor does not exist.	Check that it was not deleted.
`404`	`DOCUMENT_NOT_FOUND`	The document or record does not exist in this processor.	Pick one from the Files tab.
`409`	`FILE_PROCESSOR_SETTINGS_CONFLICT`	The settings changed while you were editing them.	Reload the processor and make your change again.
`409`	`FILE_PROCESSOR_SCHEMA_LOCKED`	The dataset's fields are fixed once it exists.	Choose Create a new dataset to use different fields.
`409`	`FILE_PROCESSOR_SOURCE_LOCKED`	A configured processor keeps the file group it reads.	Create another processor for the other file group.
`409`	`FILE_PROCESSOR_SETUP_INCOMPLETE`	The processor is not configured yet.	Finish the fields or the mapping on Settings, then choose Start processing.
`409`	`DOCUMENT_CHANGED`	Someone changed this record while you were editing it.	Reload the record and apply your edit again.
`409`	`DOCUMENT_SOURCE_CHANGED`	The selected upload changed.	Select the file again.
`409`	`PROCESSOR_AI_UNAVAILABLE`	AI is not available for the tenant, which Suggest fields and document processing need.	Make AI available. See AI in a tenant.
`409`	`DOCUMENT_AI_CALL_UNCERTAIN`	The AI analysis may not have finished.	Check your AI usage, then choose Recover analysis or run the analysis again.
`422`	`DOCUMENT_INPUT_INVALID`	The document could not be read, or the answer did not fit the fields, for example because the file is too large or a PDF too long.	Read the message. See Limits.
`502`	`DOCUMENT_PROVIDER_FAILED`	The AI provider refused or failed the request. The message names the cause, such as access, credits or a rate limit.	Fix the cause at your provider, or choose another model, and try again.
`503`	`FILE_SET_PROCESSING_NOT_SCHEDULED`	Your file is stored, but processing could not be queued.	Upload the file again to resume processing.

See Documents and spreadsheets.

Messages in the app

The app shows these messages as written. An ellipsis stands for a value Beetl fills in, such as a list of names.

Message	Meaning	What to do
Sign in to continue.	Your session ended.	Sign in again.
The tenant default object store is not configured.	The tenant has no default object store, so nothing can be written.	A TenantAdmin adds one under Settings → Tenant → Object storage. See Tenants and roles.
This workspace is suspended.	The tenant is suspended.	Contact Beetl.
Something went wrong. Please try again.	The request could not be completed, and Beetl gives no reason.	Try again. If it keeps happening, contact Beetl.

Connections and syncs

Message	Meaning	What to do
Reauthorization required. Reconnect with OAuth.	The provider no longer accepts the connection's authorization.	Open the connection and choose Reconnect with OAuth.
The provider requires a new authorization. Reconnect the Connection.	The provider rejected the stored authorization during a test or OAuth step.	Choose Reconnect with OAuth.
The provider could not complete authorization. Stored credentials were preserved.	The provider's authorization failed for a temporary reason.	Try again later. The saved authorization is unchanged.
The Connection authorization expired. Start again.	The OAuth sign-in was not finished in time.	Start the sign-in again and finish it within 10 minutes.
This Connection is paused.	The connection is paused.	Choose Resume.
This Connection is not ready to run.	The connection is not authenticated yet.	Finish the credentials or OAuth step.
Delete the Connections using these credentials first.	Saved credentials are still in use.	Delete or change the connections that use them.

See Integrations and Runs.

File Sets

Message	Meaning	What to do
Upload a CSV, NDJSON, or Parquet file.	The file's format differs from the format the set took from its first file.	Add the file to a set of its own, or convert it to the set's format. Documents go to a Documents processor.
The uploaded file is empty.	The file has no content.	Upload a file with data.
This FileSet name is already taken.	Another File Set has that name.	Choose another name.
Your file is stored, but processing could not be queued. Retry this upload to resume processing.	The file was saved, but the processor did not start.	Upload the file again.

See File Sets.

Pipelines

Message	Meaning	What to do
A pipeline with this name already exists.	Pipeline names are unique in a tenant.	Choose another name.
Missing deploy run variables: …	The pipeline uses `run.*` values and the deploy did not supply them.	Enter the values when you deploy. See Template variables.
One or more source data sets no longer exist.	A source dataset was deleted or replaced.	Select the current dataset as the source.
The pipeline changed. Refresh and try again.	Someone saved a newer version while you edited.	Reload the pipeline and make your change again.

See Deploy and trigger.

Queries

Message	Meaning	What to do
The query timed out.	The query ran for longer than 30 minutes.	Filter or aggregate earlier in the query.
Query result exceeded the byte limit of …	The result, or the data read from external tables, passed 64 MiB.	Select fewer columns, aggregate, or filter external tables in the query.
Query result not found or expired.	The result is older than 7 days, or it belongs to someone else.	Run the query again.

See Query results.

Automations

Message	Meaning	What to do
Automations may run at most once every 15 minutes.	The schedule would run twice within 15 minutes.	Choose a less frequent schedule.
Choose a schedule with a future occurrence.	The schedule never runs again.	Fix the cron expression.
Add no more than 20 suggested queries.	There are more than 20 starting queries.	Remove some.
Use a unique name for each suggested query.	2 starting queries share a name.	Rename one.
Suggested queries may contain at most 64000 SQL characters in total.	The starting queries are too long together.	Shorten or remove some.
Choose one of the offered models: …	The selected model is not offered in this tenant.	Pick a listed model, or leave the default.
This Automation is already running.	A run is in progress.	Wait for it to finish.
Wait for the current run to finish before deleting this Automation.	You cannot delete an automation during a run.	Delete it after the run ends.

See Automations.

Troubleshooting

Webhook

MCP setup

On this page