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.codeis stable and listed below. Branch on it, not onmessage.error.retryablesays whether repeating the same request can succeed. ForRATE_LIMITED, waiterror.retryAfterseconds (also theRetry-Afterheader).error.issueslists field problems (path,message) for validation errors.error.detailscarries code-specific facts, such asdetails.featureforFEATURE_DISABLEDordetails.connectionIdforCONNECTION_DISABLED.requestIdequals theX-Request-Idresponse header. Send your ownX-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)
| Code | HTTP | Retryable | Meaning |
|---|---|---|---|
BOT_CHECK_FAILED | 400 | no | The bot check failed or no Turnstile token was sent; complete the check and resubmit. |
CONFIRMATION_MISMATCH | 400 | no | The typed confirmation does not match. |
HTTP_EXCEPTION | 400 | no | An OAuth route refused the request; see message. |
INVALID_CALLBACK | 400 | no | The OAuth callback is invalid or expired. |
INVALID_CURSOR | 400 | no | The cursor is invalid for this list; restart from the first page. |
INVALID_LIMIT | 400 | no | The limit must be a whole number. |
INVALID_METRIC | 400 | no | The metric has no ceiling. |
INVALID_PROVIDER_IDENTITY | 400 | no | The provider did not return a usable account identity. |
INVALID_REQUEST | 400 | no | The OAuth request is malformed or missing a parameter. |
INVALID_SIGNATURE | 400 | no | The webhook signature is invalid. |
INVALID_TOKEN | 400 | no | The token is invalid or expired. |
ISSUES | 400 | no | The input has problems; see issues. |
KEY_REQUIRED | 400 | no | This route describes the calling API key; call it with an API key, not a session. |
MIME_TYPE_REQUIRED | 400 | no | Give the file's MIME type. |
OAUTH_CANCELLED | 400 | no | The owner cancelled the provider consent. |
OAUTH_EXCHANGE_FAILED | 400 | no | The provider refused the authorization code exchange; start the connection again. |
POLAR_MODE_MISMATCH | 400 | no | The billing provider mode does not match this deployment. |
REQUEST_FAILED | 400 | no | The request was refused; see message. Used for HTTP statuses without a more specific code. |
RESOURCE_LIMIT | 400 | no | Too many resources were selected for this connection. |
UNSUPPORTED_OPERATION | 400 | no | The provider does not support this operation. |
VALIDATION_FAILED | 400 | no | The input does not match the schema; see issues[].path. |
WRONG_FILE_TYPE | 400 | no | The file is not of the required type. |
CONFIRMATION_REQUIRED | 405 | no | Confirm the action with the documented confirmation request. |
METHOD_NOT_ALLOWED | 405 | no | The HTTP method is not supported on this route. |
BUDGET_EXCEEDED | 413 | no | The source read budget for this operation was used up; narrow the read. |
LIMIT_EXCEEDED | 413 | no | A size or row limit was exceeded; see details.limit. |
PAYLOAD_TOO_LARGE | 413 | no | The request body exceeds the route's size cap. |
STORAGE_BUDGET_EXCEEDED | 413 | no | The stored-result budget was exceeded. |
JSON_REQUIRED | 415 | no | Send the request body as application/json. |
Authentication, plan and access (401, 402, 403)
| Code | HTTP | Retryable | Meaning |
|---|---|---|---|
PROVIDER_TOKEN_EXPIRED | 401 | no | The provider token expired; reconnect. |
UNAUTHENTICATED | 401 | no | No valid credential was presented. |
PROVIDER_PLAN_REQUIRED | 402 | no | The provider account's plan does not include this API. |
ACCOUNT_SUSPENDED | 403 | no | The account is suspended; contact support. |
EMAIL_VERIFICATION_REQUIRED | 403 | no | Verify the email address first. |
FEATURE_NOT_INCLUDED | 403 | no | The current plan does not include this feature. |
FORBIDDEN | 403 | no | The request is not allowed for this principal. |
INSUFFICIENT_SCOPE | 403 | no | The credential was not granted the scope this operation needs. |
MISSING_PROVIDER_SCOPE | 403 | no | The provider grant lacks a scope; reconnect and approve it. |
OPERATOR_REQUIRED | 403 | no | Only an operator may do this. |
ORIGIN_DENIED | 403 | no | The request's Origin is not allowed for this cookie-authenticated route. |
PERMISSION_DENIED | 403 | no | The credential lacks a required scope or plan. |
PROVIDER_ACCESS_DENIED | 403 | no | The provider denied access to this resource. |
PROVIDER_SERVICE_DISABLED | 403 | no | The provider API is disabled for the integration project. |
REAUTH_REQUIRED | 403 | no | Sign in again (recent authentication is required). |
S3_NETWORK_POLICY | 403 | no | Object storage verification: The host resolves to a private or reserved address, which Xentropy does not connect to. See details.stage. |
SCOPE_REQUIRED | 403 | no | The credential lacks the blog scope this route needs. |
SECOND_FACTOR_REQUIRED | 403 | no | Enrol a second factor before using this console. |
STEP_UP_METHOD | 403 | no | This second-factor method cannot satisfy the step-up. |
STEP_UP_REQUIRED | 403 | no | A fresh second-factor check is required for this action. |
TWO_FACTOR_ENROLMENT_DISABLED | 403 | no | Two-factor enrolment is switched off on this deployment. |
Not found and conflicts (404, 409)
| Code | HTTP | Retryable | Meaning |
|---|---|---|---|
FOLDER_NOT_FOUND | 404 | no | The folder does not exist or is not yours; list folders with folders_list. |
NOT_FOUND | 404 | no | The resource does not exist or is not visible to this principal. |
PROVIDER_FILE_NOT_FOUND | 404 | no | The provider file does not exist or is not shared with the connection. |
APPROVAL_REQUIRED | 409 | no | The post needs approval first. |
ASYNC_REFRESH_REQUIRED | 409 | no | This artifact refreshes in the background; use artifacts_refresh_request. |
AUTHORIZATION_CHANGED | 409 | no | The connection's authorization changed during the operation; retry from a fresh read. |
CANCELLED | 409 | no | The operation was cancelled. |
CANCELLED_BY_OWNER | 409 | no | The owner cancelled the export. |
CHANGE_PENDING | 409 | no | A plan change is already pending. |
CHANGE_UNAVAILABLE | 409 | no | This plan change is not available. |
CHECKOUT_PENDING | 409 | no | A checkout is already open; resume it. |
COMMAND_REQUIRES_REVIEW | 409 | no | The billing command needs staff review. |
CONNECTION_ACTIVE | 409 | no | Disconnect the connection before removing it permanently. |
CONNECTION_DISABLED | 409 | no | The connection exists but is disabled; re-enable it in the console. |
CONNECTION_IN_USE | 409 | no | Datasets still read this connection; see details.datasets. |
CURRENT_PLAN | 409 | no | The account is already on this plan. |
DATASET_IN_USE | 409 | no | Live artifacts still use this dataset; see details.live. |
DUPLICATE_SUBSCRIPTION | 409 | no | The account already has a subscription. |
FOLDER_NAME_TAKEN | 409 | no | A sibling folder already has this name (case-insensitive); see details.existingFolderId. |
IDEMPOTENCY_CONFLICT | 409 | no | The idempotency key was reused with a different request. |
IN_USE | 409 | no | The item is still referenced; see details. |
INVALID_GRANT | 409 | no | The provider grant is no longer valid; reconnect. |
INVALID_STATE | 409 | no | The resource is not in a state that allows this operation. |
NOT_CANCELING | 409 | no | The subscription is not scheduled to cancel. |
NOT_CANCELLABLE | 409 | no | The job already finished or cannot be cancelled. |
NOT_DELETABLE | 409 | no | This item cannot be deleted. |
OFFLINE_GRANT_REQUIRED | 409 | no | The provider did not grant offline access; reconnect and approve it. |
OPERATION_IN_PROGRESS | 409 | yes | The same idempotency key is still running; retry later. |
PAYMENT_SETUP_REQUIRED | 409 | no | Add a payment method first. |
PREVIEW_EXPIRED | 409 | no | The price preview expired; preview again. |
RECONNECT_REQUIRED | 409 | no | The connection's credentials expired or were revoked; reconnect it. |
REFRESH_IN_PROGRESS | 409 | yes | A provider token refresh is in progress; retry shortly. |
SLUG_TAKEN | 409 | no | The slug is already in use. |
SOURCE_CHANGED | 409 | no | The source changed while it was read; retry. |
SOURCE_MISSING | 409 | no | The artifact's data source was deleted; rebind it with artifacts_update. |
SOURCE_UNCHANGED | 409 | no | The source has not changed since the last read. |
SUBSCRIPTION_EXISTS | 409 | no | A subscription already exists. |
UNKNOWN_PRICE | 409 | no | The price is unknown to this deployment. |
VALIDATION_EXPIRED | 409 | no | The validated preview is too old; validate again. |
VERSION_CONFLICT | 409 | no | The resource changed since it was read; re-read and retry. |
WRITE_RETRY_REQUIRED | 409 | no | A write's outcome is uncertain; read the target before retrying. |
WRONG_ACCOUNT | 409 | no | The provider account differs from the one this connection uses. |
Rejected input (422)
| Code | HTTP | Retryable | Meaning |
|---|---|---|---|
CAPABILITY_MISMATCH | 422 | no | No renderer supports this export. |
CARDINALITY_VIOLATION | 422 | no | A join produced duplicate keys its cardinality forbids; see details. |
CONNECTION_TYPE_UNSUPPORTED | 422 | no | This connection type is not supported here. |
COST_LIMIT_EXCEEDED | 422 | no | The query's estimated cost exceeds the connection's cap; see details. |
DECOMPRESSION_LIMIT | 422 | no | The compressed file expands beyond the allowed ratio or size. |
DEPTH_EXCEEDED | 422 | no | The document nests deeper than allowed. |
DESTINATION_UNREACHABLE | 422 | no | The destination host is not reachable from Xentropy. |
DUPLICATE_HEADER | 422 | no | The CSV header repeats a column name. |
EMBED_UNAVAILABLE | 422 | no | An embedded artifact is not available yet; see issues. |
EMPTY_INPUT | 422 | no | The file or records are empty. |
EMPTY_RENDER | 422 | no | The chart rendered no data marks; see details.reason. |
ENCODING_UNSUPPORTED | 422 | no | The file is not UTF-8 text. |
FEATURE_DISABLED | 422 | no | This deployment has the feature switched off; see details.feature. |
FEEDBACK_SUBJECT_INVALID | 422 | no | The feedback subject is not valid. |
FOLDER_CYCLE | 422 | no | A folder cannot be moved under itself or one of its own subfolders. |
FOLDER_DEPTH_EXCEEDED | 422 | no | Folders nest at most 5 levels deep; see details.resultingDepth. |
FOLDER_LIMIT_REACHED | 422 | no | The account already has the maximum of 1000 folders; delete or reuse one. |
FORMAT_UNSUPPORTED | 422 | no | This file format is not supported. |
INCOMPATIBLE_KEY_TYPES | 422 | no | Join keys have incompatible types. |
INCOMPLETE_DATA | 422 | no | The source returned incomplete data; retry or narrow the read. |
INCONSISTENT_SOURCES | 422 | no | The plan's sources are inconsistent with each other. |
INVALID_SHAPE | 422 | no | The data does not have a usable tabular shape. |
MATCH_RATE_VIOLATION | 422 | no | A join matched fewer rows than the plan requires. |
MOVE_FAILED | 422 | no | The bulk move was refused and nothing was applied; see details.failures[].code. |
MYSQL_AUTH | 422 | no | MYSQL verification: The credentials were rejected. See details.stage. |
MYSQL_DNS | 422 | no | MYSQL verification: The host name could not be resolved. See details.stage. |
MYSQL_NETWORK_POLICY | 422 | no | MYSQL verification: The host resolves to a private or reserved address, which Xentropy does not connect to. See details.stage. |
MYSQL_PERMISSION | 422 | no | MYSQL verification: The user may not read the selected database objects. See details.stage. |
MYSQL_TCP | 422 | no | MYSQL verification: The port could not be reached. See details.stage. |
MYSQL_TLS | 422 | no | MYSQL verification: The TLS certificate could not be verified. See details.stage. |
NULL_JOIN_KEY | 422 | no | Null join keys are not allowed. |
OPENAPI_REQUIRED | 422 | no | New API connections need an OpenAPI specification. |
OUTPUT_LIMIT_EXCEEDED | 422 | no | The rendered file exceeded the output size limit. |
PARSE_FAILED | 422 | no | The file could not be parsed; see details.line. |
PAYLOAD_INVALID | 422 | no | The export payload could not be rendered. |
POSTGRES_AUTH | 422 | no | POSTGRES verification: The credentials were rejected. See details.stage. |
POSTGRES_DNS | 422 | no | POSTGRES verification: The host name could not be resolved. See details.stage. |
POSTGRES_NETWORK_POLICY | 422 | no | POSTGRES verification: The host resolves to a private or reserved address, which Xentropy does not connect to. See details.stage. |
POSTGRES_PERMISSION | 422 | no | POSTGRES verification: The user may not read the selected database objects. See details.stage. |
POSTGRES_TCP | 422 | no | POSTGRES verification: The port could not be reached. See details.stage. |
POSTGRES_TLS | 422 | no | POSTGRES verification: The TLS certificate could not be verified. See details.stage. |
PROVIDER_DISABLED | 422 | no | This provider kind is not enabled on this deployment. |
PROVIDER_QUERY_INVALID | 422 | no | The provider rejected the query; see message. |
PROVIDER_RANGE_INVALID | 422 | no | The spreadsheet range is invalid. |
QUARANTINED | 422 | no | The export was quarantined after repeated renderer crashes. |
QUERY_NOT_READ_ONLY | 422 | no | Only read-only queries are allowed. |
RAGGED_ROW | 422 | no | A CSV row has a different number of cells than the header. |
RECORD_PATH_NOT_FOUND | 422 | no | The record path does not exist in the document. |
RENDER_FAILED | 422 | no | The renderer could not produce the file. |
RETRY_EXHAUSTED | 422 | no | The export failed on every attempt. |
S3_ACCESS_DENIED | 422 | no | Object storage verification: The access key may not list or read this bucket or prefix. See details.stage. |
S3_AUTH | 422 | no | Object storage verification: The credentials were rejected. See details.stage. |
S3_BUCKET_NOT_FOUND | 422 | no | Object storage verification: The bucket does not exist at this endpoint. See details.stage. |
S3_DNS | 422 | no | Object storage verification: The host name could not be resolved. See details.stage. |
S3_REDIRECT | 422 | no | Object storage verification: The storage endpoint redirected; use the bucket's own region. See details.stage. |
S3_TLS | 422 | no | Object storage verification: The TLS certificate could not be verified. See details.stage. |
SCHEMA_CHANGED | 422 | no | The source's schema changed; review the fields. |
SCHEMA_MISMATCH | 422 | no | The files under this prefix do not share one schema. |
SNOWFLAKE_AUTH | 422 | no | SNOWFLAKE verification: The credentials were rejected. See details.stage. |
SNOWFLAKE_DNS | 422 | no | SNOWFLAKE verification: The host name could not be resolved. See details.stage. |
SNOWFLAKE_NETWORK_POLICY | 422 | no | SNOWFLAKE verification: The host resolves to a private or reserved address, which Xentropy does not connect to. See details.stage. |
SNOWFLAKE_PERMISSION | 422 | no | SNOWFLAKE verification: The user may not read the selected database objects. See details.stage. |
SNOWFLAKE_TCP | 422 | no | SNOWFLAKE verification: The port could not be reached. See details.stage. |
SNOWFLAKE_TLS | 422 | no | SNOWFLAKE verification: The TLS certificate could not be verified. See details.stage. |
SNOWFLAKE_WAREHOUSE | 422 | no | SNOWFLAKE verification: The compute warehouse is unavailable or not granted. See details.stage. |
SOURCE_RESULT_LIMIT | 422 | no | The provider capped the result set; narrow the query. |
SQLSERVER_AUTH | 422 | no | SQLSERVER verification: The credentials were rejected. See details.stage. |
SQLSERVER_DNS | 422 | no | SQLSERVER verification: The host name could not be resolved. See details.stage. |
SQLSERVER_NETWORK_POLICY | 422 | no | SQLSERVER verification: The host resolves to a private or reserved address, which Xentropy does not connect to. See details.stage. |
SQLSERVER_PERMISSION | 422 | no | SQLSERVER verification: The user may not read the selected database objects. See details.stage. |
SQLSERVER_TCP | 422 | no | SQLSERVER verification: The port could not be reached. See details.stage. |
SQLSERVER_TLS | 422 | no | SQLSERVER verification: The TLS certificate could not be verified. See details.stage. |
TILES_NOT_SHAREABLE | 422 | no | Some dashboard tiles cannot be shared; see details.tiles. |
TIMEZONE_REQUIRED | 422 | no | A datetime value has no time zone; set the field's timezone. |
TYPE_CONVERSION_FAILED | 422 | no | An explicit type conversion failed. |
TYPE_MISMATCH | 422 | no | A value does not match its field type; see message. |
UNSAFE_MEASURE_GRAIN | 422 | no | A measure would be double counted at this grain. |
UNSUPPORTED_CARDINALITY | 422 | no | This join cardinality is not supported. |
UNSUPPORTED_SOURCE_QUERY | 422 | no | This source query cannot be used in a data plan. |
VALUE_TOO_LONG | 422 | no | A value exceeds the per-cell character limit. |
XML_DOCTYPE_REFUSED | 422 | no | XML documents with a DOCTYPE are refused. |
Rate limits (429)
| Code | HTTP | Retryable | Meaning |
|---|---|---|---|
FAIR_USE_LIMIT | 429 | no | The fair-use limit was reached; contact support to raise it. |
PROVIDER_RATE_LIMITED | 429 | yes | The provider is rate limiting this connection; retry later. |
QUOTA_EXCEEDED | 429 | no | The plan quota is used up for this period. |
RATE_LIMITED | 429 | yes | Too many requests; wait retryAfter seconds. |
Server and provider errors (5xx)
| Code | HTTP | Retryable | Meaning |
|---|---|---|---|
CONTRACT_VIOLATION | 500 | no | An internal response broke its contract; report the requestId. |
INTERNAL | 500 | yes | Unexpected server error; retry, and report the requestId if it persists. |
INTERNAL_ERROR | 500 | yes | The renderer hit an unexpected error. |
INTERNAL_SERVER_ERROR | 500 | yes | Unexpected OAuth server error; retry. |
ARTIFACT_BACKEND_NOT_CONFIGURED | 503 | no | Artifacts are not configured on this deployment. |
ARTIFACT_BACKEND_UNAVAILABLE | 503 | yes | The artifacts backend is temporarily unavailable. |
AUTH_NOT_CONFIGURED | 503 | no | Sign-in is not configured on this deployment. |
AUTH_UNAVAILABLE | 503 | yes | The identity service is temporarily unavailable. |
BILLING_BUSY | 503 | yes | Billing is busy; retry shortly. |
BILLING_UNAVAILABLE | 503 | yes | Billing is temporarily unavailable. |
BLOG_NOT_CONFIGURED | 503 | no | The blog is not configured on this deployment. |
CIRCUIT_BREAKER_OPEN | 503 | yes | Rendering is paused after repeated failures; retry later. |
CLEANUP_FAILED | 503 | yes | The renderer failed to clean up; the export is retried. |
DASHBOARD_BACKEND_NOT_CONFIGURED | 503 | no | Dashboards are not configured on this deployment. |
DELIVERY_FAILED | 503 | yes | The rendered file could not be delivered; the export is retried. |
EXECUTION_TIMEOUT | 503 | yes | The compute execution expired; retry. |
INVALID_PROVIDER_RESPONSE | 503 | yes | The provider returned an unexpected response; retry. |
ISSUER_UNAVAILABLE | 503 | yes | The identity provider is temporarily unavailable. |
METRICS_UNAVAILABLE | 503 | yes | Operational metrics are temporarily unavailable. |
PROVIDER_NOT_CONFIGURED | 503 | no | This provider's OAuth client is not configured on this deployment. |
PROVIDER_UNAVAILABLE | 503 | yes | The upstream provider is temporarily unavailable. |
PURCHASES_DISABLED | 503 | no | Purchases are switched off on this deployment. |
REFRESH_BUSY | 503 | yes | A provider token refresh is busy; retry shortly. |
SERVICE_UNAVAILABLE | 503 | yes | A dependency of this service is temporarily unavailable. |
SHUTTING_DOWN | 503 | yes | The renderer was shutting down; queue the export again. |
STARTUP_FAILED | 503 | yes | The renderer failed to start; the export is retried. |
STORAGE_UNAVAILABLE | 503 | yes | File storage is temporarily unavailable. |