Docs
Agents and API

Errors

The one error envelope every REST route, MCP tool and MCP transport error uses, and the catalogue of error codes.

The error envelope

Every failed request returns the same JSON envelope, whether it came from a REST route, an MCP tool call or the MCP transport:

{
  "ok": false,
  "error": {
    "code": "VERSION_CONFLICT",
    "message": "Artifact changed.",
    "retryable": false,
    "details": { "currentVersion": 3 }
  },
  "requestId": "6b0c4f0e-6c1e-4f7a-9b8e-2f1c7d1c9a10"
}
  • error.code is stable and listed below. Branch on it, not on message.
  • error.retryable says whether repeating the same request can succeed. For RATE_LIMITED, wait error.retryAfter seconds (also the Retry-After header).
  • error.issues lists field problems (path, message) for validation errors.
  • error.details carries code-specific facts, such as details.feature for FEATURE_DISABLED or details.connectionId for CONNECTION_DISABLED.
  • requestId equals the X-Request-Id response header. Send your own X-Request-Id (letters, digits, ., _, -; up to 128 characters) to correlate, and quote it when you contact support.

MCP errors

In MCP tool results the envelope is the structuredContent of a result with isError: true. JSON-RPC protocol errors (such as -32601 method not found) keep the shape the MCP specification defines.

The codes below are grouped by HTTP status. error.code is the stable value to branch on.

Invalid requests (400, 405, 413, 415)

CodeHTTPRetryableMeaning
BOT_CHECK_FAILED400noThe bot check failed or no Turnstile token was sent; complete the check and resubmit.
CONFIRMATION_MISMATCH400noThe typed confirmation does not match.
HTTP_EXCEPTION400noAn OAuth route refused the request; see message.
INVALID_CALLBACK400noThe OAuth callback is invalid or expired.
INVALID_CURSOR400noThe cursor is invalid for this list; restart from the first page.
INVALID_LIMIT400noThe limit must be a whole number.
INVALID_METRIC400noThe metric has no ceiling.
INVALID_PROVIDER_IDENTITY400noThe provider did not return a usable account identity.
INVALID_REQUEST400noThe OAuth request is malformed or missing a parameter.
INVALID_SIGNATURE400noThe webhook signature is invalid.
INVALID_TOKEN400noThe token is invalid or expired.
ISSUES400noThe input has problems; see issues.
KEY_REQUIRED400noThis route describes the calling API key; call it with an API key, not a session.
MIME_TYPE_REQUIRED400noGive the file's MIME type.
OAUTH_CANCELLED400noThe owner cancelled the provider consent.
OAUTH_EXCHANGE_FAILED400noThe provider refused the authorization code exchange; start the connection again.
POLAR_MODE_MISMATCH400noThe billing provider mode does not match this deployment.
REQUEST_FAILED400noThe request was refused; see message. Used for HTTP statuses without a more specific code.
RESOURCE_LIMIT400noToo many resources were selected for this connection.
UNSUPPORTED_OPERATION400noThe provider does not support this operation.
VALIDATION_FAILED400noThe input does not match the schema; see issues[].path.
WRONG_FILE_TYPE400noThe file is not of the required type.
CONFIRMATION_REQUIRED405noConfirm the action with the documented confirmation request.
METHOD_NOT_ALLOWED405noThe HTTP method is not supported on this route.
BUDGET_EXCEEDED413noThe source read budget for this operation was used up; narrow the read.
LIMIT_EXCEEDED413noA size or row limit was exceeded; see details.limit.
PAYLOAD_TOO_LARGE413noThe request body exceeds the route's size cap.
STORAGE_BUDGET_EXCEEDED413noThe stored-result budget was exceeded.
JSON_REQUIRED415noSend the request body as application/json.

Authentication, plan and access (401, 402, 403)

CodeHTTPRetryableMeaning
PROVIDER_TOKEN_EXPIRED401noThe provider token expired; reconnect.
UNAUTHENTICATED401noNo valid credential was presented.
PROVIDER_PLAN_REQUIRED402noThe provider account's plan does not include this API.
ACCOUNT_SUSPENDED403noThe account is suspended; contact support.
EMAIL_VERIFICATION_REQUIRED403noVerify the email address first.
FEATURE_NOT_INCLUDED403noThe current plan does not include this feature.
FORBIDDEN403noThe request is not allowed for this principal.
INSUFFICIENT_SCOPE403noThe credential was not granted the scope this operation needs.
MISSING_PROVIDER_SCOPE403noThe provider grant lacks a scope; reconnect and approve it.
OPERATOR_REQUIRED403noOnly an operator may do this.
ORIGIN_DENIED403noThe request's Origin is not allowed for this cookie-authenticated route.
PERMISSION_DENIED403noThe credential lacks a required scope or plan.
PROVIDER_ACCESS_DENIED403noThe provider denied access to this resource.
PROVIDER_SERVICE_DISABLED403noThe provider API is disabled for the integration project.
REAUTH_REQUIRED403noSign in again (recent authentication is required).
S3_NETWORK_POLICY403noObject storage verification: The host resolves to a private or reserved address, which Xentropy does not connect to. See details.stage.
SCOPE_REQUIRED403noThe credential lacks the blog scope this route needs.
SECOND_FACTOR_REQUIRED403noEnrol a second factor before using this console.
STEP_UP_METHOD403noThis second-factor method cannot satisfy the step-up.
STEP_UP_REQUIRED403noA fresh second-factor check is required for this action.
TWO_FACTOR_ENROLMENT_DISABLED403noTwo-factor enrolment is switched off on this deployment.

Not found and conflicts (404, 409)

CodeHTTPRetryableMeaning
FOLDER_NOT_FOUND404noThe folder does not exist or is not yours; list folders with folders_list.
NOT_FOUND404noThe resource does not exist or is not visible to this principal.
PROVIDER_FILE_NOT_FOUND404noThe provider file does not exist or is not shared with the connection.
APPROVAL_REQUIRED409noThe post needs approval first.
ASYNC_REFRESH_REQUIRED409noThis artifact refreshes in the background; use artifacts_refresh_request.
AUTHORIZATION_CHANGED409noThe connection's authorization changed during the operation; retry from a fresh read.
CANCELLED409noThe operation was cancelled.
CANCELLED_BY_OWNER409noThe owner cancelled the export.
CHANGE_PENDING409noA plan change is already pending.
CHANGE_UNAVAILABLE409noThis plan change is not available.
CHECKOUT_PENDING409noA checkout is already open; resume it.
COMMAND_REQUIRES_REVIEW409noThe billing command needs staff review.
CONNECTION_ACTIVE409noDisconnect the connection before removing it permanently.
CONNECTION_DISABLED409noThe connection exists but is disabled; re-enable it in the console.
CONNECTION_IN_USE409noDatasets still read this connection; see details.datasets.
CURRENT_PLAN409noThe account is already on this plan.
DATASET_IN_USE409noLive artifacts still use this dataset; see details.live.
DUPLICATE_SUBSCRIPTION409noThe account already has a subscription.
FOLDER_NAME_TAKEN409noA sibling folder already has this name (case-insensitive); see details.existingFolderId.
IDEMPOTENCY_CONFLICT409noThe idempotency key was reused with a different request.
IN_USE409noThe item is still referenced; see details.
INVALID_GRANT409noThe provider grant is no longer valid; reconnect.
INVALID_STATE409noThe resource is not in a state that allows this operation.
NOT_CANCELING409noThe subscription is not scheduled to cancel.
NOT_CANCELLABLE409noThe job already finished or cannot be cancelled.
NOT_DELETABLE409noThis item cannot be deleted.
OFFLINE_GRANT_REQUIRED409noThe provider did not grant offline access; reconnect and approve it.
OPERATION_IN_PROGRESS409yesThe same idempotency key is still running; retry later.
PAYMENT_SETUP_REQUIRED409noAdd a payment method first.
PREVIEW_EXPIRED409noThe price preview expired; preview again.
RECONNECT_REQUIRED409noThe connection's credentials expired or were revoked; reconnect it.
REFRESH_IN_PROGRESS409yesA provider token refresh is in progress; retry shortly.
SLUG_TAKEN409noThe slug is already in use.
SOURCE_CHANGED409noThe source changed while it was read; retry.
SOURCE_MISSING409noThe artifact's data source was deleted; rebind it with artifacts_update.
SOURCE_UNCHANGED409noThe source has not changed since the last read.
SUBSCRIPTION_EXISTS409noA subscription already exists.
UNKNOWN_PRICE409noThe price is unknown to this deployment.
VALIDATION_EXPIRED409noThe validated preview is too old; validate again.
VERSION_CONFLICT409noThe resource changed since it was read; re-read and retry.
WRITE_RETRY_REQUIRED409noA write's outcome is uncertain; read the target before retrying.
WRONG_ACCOUNT409noThe provider account differs from the one this connection uses.

Rejected input (422)

CodeHTTPRetryableMeaning
CAPABILITY_MISMATCH422noNo renderer supports this export.
CARDINALITY_VIOLATION422noA join produced duplicate keys its cardinality forbids; see details.
CONNECTION_TYPE_UNSUPPORTED422noThis connection type is not supported here.
COST_LIMIT_EXCEEDED422noThe query's estimated cost exceeds the connection's cap; see details.
DECOMPRESSION_LIMIT422noThe compressed file expands beyond the allowed ratio or size.
DEPTH_EXCEEDED422noThe document nests deeper than allowed.
DESTINATION_UNREACHABLE422noThe destination host is not reachable from Xentropy.
DUPLICATE_HEADER422noThe CSV header repeats a column name.
EMBED_UNAVAILABLE422noAn embedded artifact is not available yet; see issues.
EMPTY_INPUT422noThe file or records are empty.
EMPTY_RENDER422noThe chart rendered no data marks; see details.reason.
ENCODING_UNSUPPORTED422noThe file is not UTF-8 text.
FEATURE_DISABLED422noThis deployment has the feature switched off; see details.feature.
FEEDBACK_SUBJECT_INVALID422noThe feedback subject is not valid.
FOLDER_CYCLE422noA folder cannot be moved under itself or one of its own subfolders.
FOLDER_DEPTH_EXCEEDED422noFolders nest at most 5 levels deep; see details.resultingDepth.
FOLDER_LIMIT_REACHED422noThe account already has the maximum of 1000 folders; delete or reuse one.
FORMAT_UNSUPPORTED422noThis file format is not supported.
INCOMPATIBLE_KEY_TYPES422noJoin keys have incompatible types.
INCOMPLETE_DATA422noThe source returned incomplete data; retry or narrow the read.
INCONSISTENT_SOURCES422noThe plan's sources are inconsistent with each other.
INVALID_SHAPE422noThe data does not have a usable tabular shape.
MATCH_RATE_VIOLATION422noA join matched fewer rows than the plan requires.
MOVE_FAILED422noThe bulk move was refused and nothing was applied; see details.failures[].code.
MYSQL_AUTH422noMYSQL verification: The credentials were rejected. See details.stage.
MYSQL_DNS422noMYSQL verification: The host name could not be resolved. See details.stage.
MYSQL_NETWORK_POLICY422noMYSQL verification: The host resolves to a private or reserved address, which Xentropy does not connect to. See details.stage.
MYSQL_PERMISSION422noMYSQL verification: The user may not read the selected database objects. See details.stage.
MYSQL_TCP422noMYSQL verification: The port could not be reached. See details.stage.
MYSQL_TLS422noMYSQL verification: The TLS certificate could not be verified. See details.stage.
NULL_JOIN_KEY422noNull join keys are not allowed.
OPENAPI_REQUIRED422noNew API connections need an OpenAPI specification.
OUTPUT_LIMIT_EXCEEDED422noThe rendered file exceeded the output size limit.
PARSE_FAILED422noThe file could not be parsed; see details.line.
PAYLOAD_INVALID422noThe export payload could not be rendered.
POSTGRES_AUTH422noPOSTGRES verification: The credentials were rejected. See details.stage.
POSTGRES_DNS422noPOSTGRES verification: The host name could not be resolved. See details.stage.
POSTGRES_NETWORK_POLICY422noPOSTGRES verification: The host resolves to a private or reserved address, which Xentropy does not connect to. See details.stage.
POSTGRES_PERMISSION422noPOSTGRES verification: The user may not read the selected database objects. See details.stage.
POSTGRES_TCP422noPOSTGRES verification: The port could not be reached. See details.stage.
POSTGRES_TLS422noPOSTGRES verification: The TLS certificate could not be verified. See details.stage.
PROVIDER_DISABLED422noThis provider kind is not enabled on this deployment.
PROVIDER_QUERY_INVALID422noThe provider rejected the query; see message.
PROVIDER_RANGE_INVALID422noThe spreadsheet range is invalid.
QUARANTINED422noThe export was quarantined after repeated renderer crashes.
QUERY_NOT_READ_ONLY422noOnly read-only queries are allowed.
RAGGED_ROW422noA CSV row has a different number of cells than the header.
RECORD_PATH_NOT_FOUND422noThe record path does not exist in the document.
RENDER_FAILED422noThe renderer could not produce the file.
RETRY_EXHAUSTED422noThe export failed on every attempt.
S3_ACCESS_DENIED422noObject storage verification: The access key may not list or read this bucket or prefix. See details.stage.
S3_AUTH422noObject storage verification: The credentials were rejected. See details.stage.
S3_BUCKET_NOT_FOUND422noObject storage verification: The bucket does not exist at this endpoint. See details.stage.
S3_DNS422noObject storage verification: The host name could not be resolved. See details.stage.
S3_REDIRECT422noObject storage verification: The storage endpoint redirected; use the bucket's own region. See details.stage.
S3_TLS422noObject storage verification: The TLS certificate could not be verified. See details.stage.
SCHEMA_CHANGED422noThe source's schema changed; review the fields.
SCHEMA_MISMATCH422noThe files under this prefix do not share one schema.
SNOWFLAKE_AUTH422noSNOWFLAKE verification: The credentials were rejected. See details.stage.
SNOWFLAKE_DNS422noSNOWFLAKE verification: The host name could not be resolved. See details.stage.
SNOWFLAKE_NETWORK_POLICY422noSNOWFLAKE verification: The host resolves to a private or reserved address, which Xentropy does not connect to. See details.stage.
SNOWFLAKE_PERMISSION422noSNOWFLAKE verification: The user may not read the selected database objects. See details.stage.
SNOWFLAKE_TCP422noSNOWFLAKE verification: The port could not be reached. See details.stage.
SNOWFLAKE_TLS422noSNOWFLAKE verification: The TLS certificate could not be verified. See details.stage.
SNOWFLAKE_WAREHOUSE422noSNOWFLAKE verification: The compute warehouse is unavailable or not granted. See details.stage.
SOURCE_RESULT_LIMIT422noThe provider capped the result set; narrow the query.
SQLSERVER_AUTH422noSQLSERVER verification: The credentials were rejected. See details.stage.
SQLSERVER_DNS422noSQLSERVER verification: The host name could not be resolved. See details.stage.
SQLSERVER_NETWORK_POLICY422noSQLSERVER verification: The host resolves to a private or reserved address, which Xentropy does not connect to. See details.stage.
SQLSERVER_PERMISSION422noSQLSERVER verification: The user may not read the selected database objects. See details.stage.
SQLSERVER_TCP422noSQLSERVER verification: The port could not be reached. See details.stage.
SQLSERVER_TLS422noSQLSERVER verification: The TLS certificate could not be verified. See details.stage.
TILES_NOT_SHAREABLE422noSome dashboard tiles cannot be shared; see details.tiles.
TIMEZONE_REQUIRED422noA datetime value has no time zone; set the field's timezone.
TYPE_CONVERSION_FAILED422noAn explicit type conversion failed.
TYPE_MISMATCH422noA value does not match its field type; see message.
UNSAFE_MEASURE_GRAIN422noA measure would be double counted at this grain.
UNSUPPORTED_CARDINALITY422noThis join cardinality is not supported.
UNSUPPORTED_SOURCE_QUERY422noThis source query cannot be used in a data plan.
VALUE_TOO_LONG422noA value exceeds the per-cell character limit.
XML_DOCTYPE_REFUSED422noXML documents with a DOCTYPE are refused.

Rate limits (429)

CodeHTTPRetryableMeaning
FAIR_USE_LIMIT429noThe fair-use limit was reached; contact support to raise it.
PROVIDER_RATE_LIMITED429yesThe provider is rate limiting this connection; retry later.
QUOTA_EXCEEDED429noThe plan quota is used up for this period.
RATE_LIMITED429yesToo many requests; wait retryAfter seconds.

Server and provider errors (5xx)

CodeHTTPRetryableMeaning
CONTRACT_VIOLATION500noAn internal response broke its contract; report the requestId.
INTERNAL500yesUnexpected server error; retry, and report the requestId if it persists.
INTERNAL_ERROR500yesThe renderer hit an unexpected error.
INTERNAL_SERVER_ERROR500yesUnexpected OAuth server error; retry.
ARTIFACT_BACKEND_NOT_CONFIGURED503noArtifacts are not configured on this deployment.
ARTIFACT_BACKEND_UNAVAILABLE503yesThe artifacts backend is temporarily unavailable.
AUTH_NOT_CONFIGURED503noSign-in is not configured on this deployment.
AUTH_UNAVAILABLE503yesThe identity service is temporarily unavailable.
BILLING_BUSY503yesBilling is busy; retry shortly.
BILLING_UNAVAILABLE503yesBilling is temporarily unavailable.
BLOG_NOT_CONFIGURED503noThe blog is not configured on this deployment.
CIRCUIT_BREAKER_OPEN503yesRendering is paused after repeated failures; retry later.
CLEANUP_FAILED503yesThe renderer failed to clean up; the export is retried.
DASHBOARD_BACKEND_NOT_CONFIGURED503noDashboards are not configured on this deployment.
DELIVERY_FAILED503yesThe rendered file could not be delivered; the export is retried.
EXECUTION_TIMEOUT503yesThe compute execution expired; retry.
INVALID_PROVIDER_RESPONSE503yesThe provider returned an unexpected response; retry.
ISSUER_UNAVAILABLE503yesThe identity provider is temporarily unavailable.
METRICS_UNAVAILABLE503yesOperational metrics are temporarily unavailable.
PROVIDER_NOT_CONFIGURED503noThis provider's OAuth client is not configured on this deployment.
PROVIDER_UNAVAILABLE503yesThe upstream provider is temporarily unavailable.
PURCHASES_DISABLED503noPurchases are switched off on this deployment.
REFRESH_BUSY503yesA provider token refresh is busy; retry shortly.
SERVICE_UNAVAILABLE503yesA dependency of this service is temporarily unavailable.
SHUTTING_DOWN503yesThe renderer was shutting down; queue the export again.
STARTUP_FAILED503yesThe renderer failed to start; the export is retried.
STORAGE_UNAVAILABLE503yesFile storage is temporarily unavailable.

On this page