Errors and help

Every refusal from LakehouseBox says what went wrong and what to do next. This page shows how to read one, what the most common errors want, where to look when something seems broken, and how to report a bug. Every error code a public route can answer is in the index at the end.

The short path

lhbox doctor --write-probe        # checks this machine end to end, including a write
lhbox whoami                      # which key and organisation are in use
lhbox usage                       # every limit, with your headroom
lhbox update                      # when the CLI says it is out of date
lhbox bug --title "lhbox duckdb: INSERT refused on my catalog"   # a filled-in report for the public tracker

Read the error's remedy before you retry anything.

How an error looks

The API answers every failure with one JSON object:

{"error": {
  "code": "quota_exceeded",
  "message": "This organisation is over its private storage limit: 5,400,000,000 of 5,368,709,120 bytes.",
  "limit_value": 5368709120, "current": 5400000000, "headroom": 0,
  "remedy": "… what frees space, or who raises the limit",
  "request_id": "…"}}
  • code is stable: match on it, never on message.
  • remedy, when present, is the next step. Act on it rather than retrying the same request.
  • request_id is always there. Quote it when you write to us.
  • An unexpected failure is a 500 with the same shape and a request_id.

Some errors add fields that help:

field what it tells you
field which input was wrong
limit, current, available a limit, and where you stand
retry_after_seconds when to try again; also sent as Retry-After
attempts_left how many tries remain
candidates the ids behind an ambiguous name
can_grant who can give you access
cli_outdated your lhbox is older than the published one: the published version, and how to update

An option these docs describe may be newer than your CLI. When cli_outdated appears, lhbox update installs the current one.

The CLI's exit codes

The lhbox CLI prints the same object on stderr. Its exit code says what kind of failure it was:

exit meaning what to do
0 ok
1 the input is wrong fix the values; never retry unchanged
2 a real limit or conflict a quota or a 409: change the plan, free space, or ask for a higher limit
3 authentication or permission (401, 403) the key is missing, wrong or revoked: lhbox whoami, then lhbox login; or it may not do this: the error's remedy names who can give access
4 not found no such project, catalog, namespace or table (or none you can see)
5 our side, the network, or a 429 (busy, rate_limited) safe to retry with backoff, after retry_after_seconds when it is given, except as below
6 the command line is malformed fix the command (lhbox <command> --help); never retry

An exit 5 that says outcome: unknown, or is import_outcome_unknown, is not safe to retry. The write may have landed, so check first; the remedy says how. Re-running an append writes its rows twice.

The errors you will meet most

code HTTP what it means what to do
invalid_api_key, api_key_revoked, invalid_token, missing_credential 401 the key or token is wrong, revoked or expired, or none was sent lhbox whoami names the key in use; lhbox login connects this machine again
reauth_required 401 a change that protects the account or the organisation (the password, two-factor, passkeys, deleting, single sign-on, making an admin) from a browser session not confirmed in the last 10 minutes confirm it is you on the account page and retry; an API key is never asked
key_not_confirmed 403 a key made from a sign-in that was not confirmed, used for one of those same changes do it on the account page, or confirm it is you there and make a new key (lhbox login)
session_expired 401 the browser session ended; with reason: org_session_lifetime, an organisation of yours asks its members to sign in again after a set time sign in again
forbidden 403 you hold read where write is needed, or none at all can_grant names who can give you access; ask them
insufficient_role 403 an admin's action asked by a member ask an admin of the organisation
org_policy_forbids 403 the organisation's policy keeps this to admins (publishing, connecting agents) ask an admin
connection_not_granted 403 an MCP connection asked for a catalog its person can read but that it was not granted (approved for select catalogs, the catalog made later) the person grants it under the catalog's Access tab (Grant access, the connection's token), or reconnects and chooses All catalogs
warehouse_not_found, table_not_found, namespace_not_found 404 no such catalog, namespace or table, or one you cannot see lhbox catalog list, lhbox table list; a name close to yours comes back as did_you_mean where the MCP tools answer
ambiguous_name 409 two catalogs share that name use one of the ids in candidates
quota_exceeded 409 the organisation is over its storage limit reading still works; free space, or write to us and we raise it
limit_exceeded 409 a count limit, such as catalogs per project lhbox usage shows each limit and your headroom
idempotency_key_reused 409 the same --idempotency-key was sent with a different request use a new key for a new request
creation_in_progress 409 the same catalog is being created right now wait the Retry-After and look again
confirmation_required 400 a destructive command without its confirmation repeat it with --confirm (or --yes); confirm_with names the value expected
terms_required 400 the Terms were not accepted accept them (--accept-terms, or the account page)
rate_limited 429 too many requests too fast wait retry_after_seconds; sooner is refused without running
busy 429 the shared query queue is full wait retry_after_seconds, or run the query in your own DuckDB (lhbox duckdb)
query_timeout 408 a server-side query ran past its 20 seconds filter and aggregate more in SQL, or run it in your own DuckDB, which has no time limit
store_timeout, query_unavailable, other 5xx 5xx our side retry with backoff; if it persists, check the status page and write to us with the request_id

Two refusals that come from your engine

  • A commit conflict: a 409 from the catalog, or CommitFailedException in PyIceberg and Spark. Iceberg commits are optimistic. When someone else committed to the table first, your commit is refused and should be retried on the new version. That someone can be the catalog's own maintenance. Spark retries a few times on its own; DuckDB does not. So an unattended job (DuckDB or PyIceberg) should catch the conflict, wait a few seconds and run the statement again.
  • DuckDB: "attached in read-only mode". The catalog was attached with s3://<bucket>/ instead of the bare bucket name. lhbox duckdb and lhbox connect --engine duckdb print the right ATTACH. More gotchas per engine: Engines.

Before you write to us

  1. lhbox doctor checks this machine end to end: the key, the catalog, the engine recipe. --write-probe also writes and deletes one empty file: it is the one check that sees a refused write.
  2. lhbox whoami says which key and organisation are in use. lhbox usage lists every limit with your headroom.
  3. lhbox update when the CLI says it is out of date.
  4. The status page shows whether these work right now: signing up, logging in, connecting an agent, reading and writing data, the MCP server and the website. They are checked every 5 minutes, from outside our servers.

Report a bug

Something that does not work as these docs say is a bug. Report it on the public tracker, github.com/lakehousebox/lakehousebox. Bugs, feature requests and questions are all in the open there, so you can see whether someone has already reported yours.

lhbox bug --title "lhbox duckdb: INSERT refused on my catalog"

lhbox bug opens the tracker's bug form, filled in with this machine's lhbox, operating system, Python and DuckDB versions. Nothing is sent until you submit it. Add what you ran, the error as printed, and the output of lhbox doctor. The error's code and request_id matter most. --what and --command fill those fields from the command line. Anything in them shaped like a key or a secret is replaced by <redacted>. Piped, it prints the link and the same details as JSON instead of opening a browser.

The tracker is public. Never paste an API key, a catalog secret, lhbox connect --show-secrets output, a catalog token or a presigned URL. A report that needs your data, your account or a private conversation goes to hello@lakehousebox.com. A security vulnerability is never a public issue: report it privately on GitHub or by email.

Agents: when something looks like a bug in LakehouseBox rather than in your SQL, read the error's remedy first. If it is still a bug, run lhbox bug --title "…" --what "…". Leave out keys, secrets and the person's data.

The person: sees the link it prints, and decides whether to file it. File the issue yourself (gh issue create --repo lakehousebox/lakehousebox) only when they ask you to.

Getting help

Write to hello@lakehousebox.com with the command or request, the request_id and what you expected. The first answer comes within 2 business days on every plan, and within 1 business day on Enterprise (support). Bugs and requests can also go on the public tracker. Security reports go to the same address or to a private GitHub report (security.txt).

Every error code

Built from the API reference: each code a public route documents, its HTTP status and the routes that answer it (what each means on that route is there).

codeHTTPanswered by
access_denied403POST /oauth/register
account_deleted401POST /v1/tokens
address_not_verified403PATCH /v1/artifacts/{artifact_id}
agent_not_found404PATCH /v1/artifacts/{artifact_id}
agents_md_changed409PUT /v1/warehouses/{warehouse_id}/agents-md
already_exists409POST /v1/signup/start, POST /v1/signup/verify, POST /v1/projects, PATCH /v1/projects/{project_id}, POST /v1/warehouses, POST /v1/warehouses/{warehouse_id}/restore and 9 more
ambiguous_name409GET /v1/warehouses/{warehouse_id}, PATCH /v1/warehouses/{warehouse_id}, POST /v1/warehouses/{warehouse_id}/measure, POST /v1/warehouses/{warehouse_id}/restore, POST /v1/warehouses/{warehouse_id}/rotate, GET /v1/sinks/{sink_id} and 2 more
anonymous_connection409PUT /v1/orgs/{org_id}/connections/{name}/secret
anonymous_not_enabled403POST /v1/agent/identity, POST /v1/oauth/authorize/set-up
api_key_expired401POST /v1/tokens
api_key_not_found404GET /v1/api-keys/{key_id}, PATCH /v1/api-keys/{key_id}, DELETE /v1/api-keys/{key_id}
api_key_revoked401POST /v1/tokens
artifact_already_shared409POST /v1/artifacts/{artifact_id}/people
artifact_busy429GET /v1/artifacts/{artifact_id}/export, GET /v1/artifacts/{artifact_id}/check, GET /v1/artifacts/{artifact_id}/files, POST /v1/artifacts/{artifact_id}/duplicate
artifact_catalog_gone409POST /v1/artifacts/{artifact_id}/duplicate
artifact_gone410POST /v1/artifacts/{artifact_id}/restore
artifact_has_owner409POST /v1/artifacts/{artifact_id}/owner
artifact_incomplete409POST /v1/artifacts/{artifact_id}/versions/{version}/publish
artifact_limit409POST /v1/artifacts, POST /v1/artifacts/{artifact_id}/duplicate, POST /v1/artifacts/{artifact_id}/restore
artifact_needs_catalog_read403POST /v1/artifacts, POST /v1/artifacts/{artifact_id}/duplicate
artifact_needs_person403POST /v1/artifacts
artifact_not_deleted409POST /v1/artifacts/{artifact_id}/restore
artifact_not_found404POST /v1/artifacts, PATCH /v1/artifacts/{artifact_id}, POST /v1/artifacts/{artifact_id}/people, DELETE /v1/artifacts/{artifact_id}/people/{principal_id}, GET /v1/artifacts/{artifact_id}/export, GET /v1/artifacts/{artifact_id}/check and 6 more
artifact_not_published409POST /v1/artifacts/{artifact_id}/people, GET /v1/artifacts/{artifact_id}/export, GET /v1/artifacts/{artifact_id}/check, GET /v1/artifacts/{artifact_id}/files, POST /v1/artifacts/{artifact_id}/duplicate, POST /v1/artifacts/{artifact_id}/open
artifact_not_yours403POST /v1/artifacts, PATCH /v1/artifacts/{artifact_id}, DELETE /v1/artifacts/{artifact_id}/people/{principal_id}, DELETE /v1/artifacts/{artifact_id}, POST /v1/artifacts/{artifact_id}/restore
artifact_people_limit409POST /v1/artifacts/{artifact_id}/people
artifact_person_not_member404POST /v1/artifacts/{artifact_id}/people
artifact_person_only403PATCH /v1/artifacts/{artifact_id}, POST /v1/artifacts/{artifact_id}/people, DELETE /v1/artifacts/{artifact_id}/people/{principal_id}, POST /v1/artifacts/{artifact_id}/duplicate
artifact_public_blocked403PATCH /v1/artifacts/{artifact_id}
artifact_public_private_data409PATCH /v1/artifacts/{artifact_id}
artifact_share_not_found404DELETE /v1/artifacts/{artifact_id}/people/{principal_id}
artifact_storage_error502POST /v1/artifacts, GET /v1/artifacts/{artifact_id}/check
artifact_too_large413POST /v1/artifacts, PUT /v1/artifacts/{artifact_id}/versions/{version}/files/{name}
artifact_type_refused415PUT /v1/artifacts/{artifact_id}/versions/{version}/files/{name}
artifact_upload_timeout408PUT /v1/artifacts/{artifact_id}/versions/{version}/files/{name}
artifact_uploads_busy429PUT /v1/artifacts/{artifact_id}/versions/{version}/files/{name}
artifact_version_published409PUT /v1/artifacts/{artifact_id}/versions/{version}/files/{name}, POST /v1/artifacts/{artifact_id}/versions/{version}/publish
authorization_pending400POST /v1/auth/device/token
bad_name400POST /v1/warehouses/{warehouse_id}/uploaders, POST /v1/sinks
batch_too_large413POST /v1/sinks/{sink_id}
body_too_large413POST /d/{token}, POST /v1/sinks/{sink_id}/test
brand_link_domain400PATCH /v1/orgs/{org_id}/brand
brand_logo_not_found404GET /v1/orgs/{org_id}/brand/logo
break_glass_restricted403any authenticated route outside the ones that repair sign-in, with the break-glass admin's session while its organisation enforces single sign-on, except under the ENS profile, where the break-glass admin is refused like any other password session (sso_required) (Authentication)
bucket_leftover_from_deletion409POST /v1/warehouses
busy429GET /v1/object, POST /v1/query
catalog_error502POST /v1/tables, PATCH /v1/table, DELETE /v1/table, DELETE /v1/namespace, POST /v1/credentials
catalog_grant_held409PUT /v1/warehouses/{warehouse_id}/grants/{principal_id}
catalog_unavailable502POST /v1/query
change_not_found404GET /v1/changes/{change_id}, POST /v1/changes/{change_id}/restore
changed_since409POST /v1/changes/{change_id}/restore, POST /v1/changes/operations/{operation_id}/restore
checksum_mismatch409PUT /v1/warehouses/{warehouse_id}/migrations/{version}
claim_gone409POST /v1/agent/identity/claim
claim_required403POST /v1/artifacts, PATCH /v1/artifacts/{artifact_id}, POST /v1/artifacts/{artifact_id}/duplicate
code_expired410POST /v1/signup/verify, POST /v1/auth/google/link, POST /v1/auth/google/reauth/email-code/confirm
column_exists409PATCH /v1/table
column_not_found400PATCH /v1/table
completion_unknown504POST /v1/warehouses/{warehouse_id}/blobs/multipart/complete
confirmation_required400DELETE /v1/agent/identity, PUT /v1/warehouses/{warehouse_id}/grants/{principal_id}, DELETE /v1/warehouses/{warehouse_id}, POST /v1/warehouses/{warehouse_id}/public, DELETE /v1/orgs/{org_id}, DELETE /v1/me and 1 more
connection_ending409POST /v1/sandbox-token
connection_in_use409DELETE /v1/orgs/{org_id}/connections/{name}
connection_not_found404GET /v1/orgs/{org_id}/connections/{name}, PUT /v1/orgs/{org_id}/connections/{name}/secret, DELETE /v1/orgs/{org_id}/connections/{name}, PUT /v1/orgs/{org_id}/connections/{name}/use-access, PUT /v1/orgs/{org_id}/connections/{name}/grants/{principal_id}, POST /v1/orgs/{org_id}/connections/{name}/take-over and 3 more
connection_stopped409PUT /v1/orgs/{org_id}/connections/{name}/secret, PUT /v1/orgs/{org_id}/connections/{name}/owner, POST /v1/orgs/{org_id}/sources, POST /v1/orgs/{org_id}/sources/{name}/refresh
creation_in_progress409POST /v1/warehouses
creator_not_member403POST /v1/orgs/{org_id}/tokens, POST /v1/oauth/authorize/decision
creator_revoked403POST /v1/orgs/{org_id}/tokens
dedupe_recent409POST /v1/sinks/{sink_id}/dedupe
delete_in_progress409DELETE /v1/agent/identity, DELETE /v1/warehouses/{warehouse_id}, DELETE /v1/orgs/{org_id}, DELETE /v1/me
device_code_not_found404GET /v1/auth/device/pending, POST /v1/auth/device/approve, GET /v1/auth/device/status
disposable_email400POST /v1/signup/start, POST /v1/signup/verify, POST /v1/auth/signup, POST /v1/auth/google/callback
dns_unavailable503POST /v1/orgs/{org_id}/domains/{domain}/verify
domain_claimed409POST /v1/orgs/{org_id}/domains/{domain}/verify
domain_not_found404POST /v1/orgs/{org_id}/domains/{domain}/verify, DELETE /v1/orgs/{org_id}/domains/{domain}
domain_not_verified409POST /v1/orgs/{org_id}/domains/{domain}/verify
domain_under_enforced_sso409POST /v1/orgs/{org_id}/domains/{domain}/verify
edge_reads_engine400GET /v1/connection
edge_reads_off409GET /v1/connection
edge_reads_unavailable409PATCH /v1/warehouses/{warehouse_id}
email_code_required401POST /v1/auth/google/callback
email_not_verified403, 409POST /v1/auth/google/callback, PUT /v1/me/news
engine_read_only400GET /v1/connection
enterprise_feature403PUT /v1/warehouses/{warehouse_id}/grants/{principal_id}, PATCH /v1/orgs/{org_id}/brand, PUT /v1/orgs/{org_id}/brand/logo
entra_admin_required403POST /v1/setup/microsoft/finish
expires_not_supported409POST /v1/credentials
feature_not_enabled403POST /v1/agents
forbidden403PATCH /v1/projects/{project_id}, DELETE /v1/projects/{project_id}, POST /v1/warehouses, PATCH /v1/warehouses/{warehouse_id}, PUT /v1/warehouses/{warehouse_id}/grants/{principal_id}, DELETE /v1/warehouses/{warehouse_id}/grants/{principal_id} and 48 more
google_account_mismatch403POST /v1/auth/google/reauth
google_not_linked409POST /v1/auth/google/reauth, POST /v1/auth/google/reauth/email-code
google_unavailable502POST /v1/auth/google/callback
grant_from_group_rule409DELETE /v1/warehouses/{warehouse_id}/grants/{principal_id}
grant_not_found404DELETE /v1/warehouses/{warehouse_id}/grants/{principal_id}
graph_failed502POST /v1/setup/microsoft/finish
graph_unavailable503POST /v1/setup/microsoft/finish
handle_taken409POST /v1/signup/start, POST /v1/auth/signup, POST /v1/onboard
idempotency_key_reused409POST /v1/projects
identity_conflict409POST /v1/auth/google/callback
idp_org_mismatch403POST /v1/orgs/{org_id}/join, POST /v1/orgs/invitations/accept, POST /v1/auth/device/approve, POST /v1/oauth/authorize/decision
idp_org_not_member403POST /v1/projects, GET /v1/oauth/authorize/pending, POST /v1/oauth/authorize/decision, POST /v1/onboard
idp_org_only403GET /v1/oauth/authorize/pending, POST /v1/oauth/authorize/decision
immutable_field400PATCH /v1/projects/{project_id}
implicit_grant409PUT /v1/warehouses/{warehouse_id}/grants/{principal_id}, DELETE /v1/warehouses/{warehouse_id}/grants/{principal_id}
index_not_found404GET /v1/indexes/{index_id}, DELETE /v1/indexes/{index_id}
insufficient_role403PATCH /v1/orgs/{org_id}, PATCH /v1/orgs/{org_id}/policy, POST /v1/orgs/{org_id}/connections/{name}/take-over, PATCH /v1/orgs/{org_id}/members/{member_id}, DELETE /v1/orgs/{org_id}, DELETE /v1/orgs/{org_id}/members/{member_id} and 6 more
insufficient_scope403GET /v1/object, POST /v1/query
integration_needs_person403POST /v1/agents
integration_not_found404POST /v1/sql/connections
invalid_api_key401POST /v1/tokens
invalid_body400any route taking a JSON body, when the body is not UTF-8 or nests too deep to parse (reason not_utf8 or too_deep)
invalid_client400, 401GET /oauth/authorize, POST /oauth/token
invalid_client_metadata400POST /oauth/register
invalid_code401POST /v1/signup/verify, POST /v1/auth/google/link, POST /v1/auth/google/reauth/email-code/confirm
invalid_credentials401DELETE /v1/orgs/{org_id}, POST /v1/auth/reauth, POST /v1/auth/passkeys/register/start, POST /v1/auth/mfa/totp/start, POST /v1/auth/mfa/totp/disable, POST /v1/auth/password/change and 1 more
invalid_device_token401POST /d/{token}
invalid_enrol_token401POST /v1/auth/mfa/enrol/start, POST /v1/auth/mfa/enrol/confirm
invalid_expires400POST /v1/credentials
invalid_extractors400POST /v1/indexes
invalid_field400PATCH /v1/warehouses/{warehouse_id}, PATCH /v1/orgs/{org_id}/policy
invalid_files_prefix400POST /v1/warehouses/{warehouse_id}/public
invalid_google_code401POST /v1/auth/google/callback
invalid_google_token401POST /v1/auth/google/link, POST /v1/auth/google/signup
invalid_grant400POST /v1/auth/cli/token
invalid_id_token401POST /v1/auth/google/callback
invalid_image400PUT /v1/orgs/{org_id}/brand/logo
invalid_key400, 401POST /v1/sinks/{sink_id}, GET /v1/warehouses/{warehouse_id}/blobs/presign, POST /v1/warehouses/{warehouse_id}/blobs/upload, POST /v1/warehouses/{warehouse_id}/blobs/multipart, POST /v1/warehouses/{warehouse_id}/blobs/multipart/parts, POST /v1/warehouses/{warehouse_id}/blobs/multipart/abort and 2 more
invalid_login401POST /v1/auth/login
invalid_login_token401POST /v1/auth/password/set, POST /v1/auth/password/reset
invalid_mfa_code400, 401DELETE /v1/orgs/{org_id}, POST /v1/auth/login, POST /v1/auth/google/reauth, POST /v1/auth/google/reauth/email-code/confirm, POST /v1/auth/login/mfa, POST /v1/auth/mfa/enrol/confirm and 7 more
invalid_mfa_token401POST /v1/auth/login/mfa, POST /v1/auth/login/passkey/start
invalid_name400POST /v1/warehouses
invalid_passkey400, 401POST /v1/auth/login/mfa, POST /v1/auth/login/passkey, POST /v1/auth/reauth, POST /v1/auth/passkeys/register/finish, POST /v1/auth/mfa/totp/disable, POST /v1/auth/mfa/backup-codes and 2 more
invalid_path400any route, when the decoded request path carries a control character (%00 to %1F or %7F; the namespace separator %1F is accepted under /public-catalog/)
invalid_prefix400GET /v1/warehouses/{warehouse_id}/blobs
invalid_redirect_uri400POST /v1/auth/cli/authorize
invalid_refresh_token401POST /v1/auth/refresh
invalid_request400GET /oauth/authorize, POST /oauth/token
invalid_setup_token401POST /v1/setup
invalid_state400POST /v1/auth/google/callback
invalid_token400POST /v1/news/unsubscribe, POST /v1/onboarding/unsubscribe
invalid_upload_id400POST /v1/warehouses/{warehouse_id}/blobs/multipart/complete
invalid_value400any route taking a JSON body, when it holds NaN, Infinity, -Infinity or a number too large to be finite such as 1e999 (literal), an integer of more than 38 digits (digits, max_digits), or is not valid JSON (where body, the character offset as position); any route storing a number, when it is beyond a signed 64-bit integer (max_value). A sink's device route (/d/<token>) stores NaN, Infinity and -Infinity as readings, and POST /v1/signup/start, POST /v1/warehouses, PATCH /v1/warehouses/{warehouse_id}, PUT /v1/warehouses/{warehouse_id}/grants/{principal_id}, PUT /v1/warehouses/{warehouse_id}/org-access, DELETE /v1/warehouses/{warehouse_id} and 37 more
invitation_accepted409DELETE /v1/orgs/{org_id}/invitations/{invitation_id}
invitation_expired410POST /v1/orgs/invitations/accept
invitation_for_someone_else403POST /v1/orgs/invitations/accept
invitation_not_found404DELETE /v1/orgs/{org_id}/invitations/{invitation_id}, POST /v1/orgs/invitations/accept
inviter_unknown403POST /v1/orgs/{org_id}/invitations
inviter_unverified403POST /v1/orgs/{org_id}/invitations
key_column_not_found400POST /v1/sinks
key_not_confirmed403PATCH /v1/orgs/{org_id}/policy, PATCH /v1/orgs/{org_id}/members/{member_id}, DELETE /v1/orgs/{org_id}, POST /v1/orgs/{org_id}/invitations, POST /v1/orgs/{org_id}/tokens, PATCH /v1/orgs/{org_id}/tokens/{token_id} and 1 more
last_admin409PATCH /v1/orgs/{org_id}/members/{member_id}, DELETE /v1/orgs/{org_id}/members/{member_id}, DELETE /v1/me
left_organisation403POST /v1/orgs/{org_id}/join
length_required411PUT /v1/artifacts/{artifact_id}/versions/{version}/files/{name}
limit_exceeded409POST /v1/warehouses, POST /v1/warehouses/{warehouse_id}/restore, POST /v1/warehouses/{warehouse_id}/uploaders, PUT /v1/warehouses/{warehouse_id}/migrations/{version}, POST /v1/orgs/{org_id}/connections, POST /v1/orgs/{org_id}/sources and 2 more
limit_reached409POST /v1/agents
mail_error502POST /v1/signup/start, POST /v1/auth/signup, POST /v1/auth/google/reauth/email-code
managed_catalog409PUT /v1/warehouses/{warehouse_id}/org-access, POST /v1/warehouses/{warehouse_id}/rotate, POST /v1/orgs/{org_id}/invitations
mcp_human_only403POST /v1/warehouses, PUT /v1/warehouses/{warehouse_id}/org-access
member_not_found404PATCH /v1/orgs/{org_id}/members/{member_id}, DELETE /v1/orgs/{org_id}/members/{member_id}
mfa_already_enabled409POST /v1/auth/mfa/enrol/start, POST /v1/auth/mfa/enrol/confirm, POST /v1/auth/mfa/totp/start, POST /v1/auth/mfa/totp/confirm
mfa_code_required401DELETE /v1/orgs/{org_id}, POST /v1/auth/google/reauth, POST /v1/auth/google/reauth/email-code/confirm, POST /v1/auth/reauth, POST /v1/auth/passkeys/register/start, POST /v1/auth/passkeys/register/finish and 2 more
mfa_enrolment_required401, 403POST /v1/tokens, POST /v1/auth/login
mfa_not_enabled409POST /v1/auth/mfa/totp/disable, POST /v1/auth/mfa/backup-codes
mfa_not_started404POST /v1/auth/mfa/enrol/confirm, POST /v1/auth/mfa/totp/confirm
mfa_required401POST /v1/auth/login, POST /v1/auth/google/callback
mfa_required_by_policy409DELETE /v1/auth/passkeys/{passkey_id}, POST /v1/auth/mfa/totp/disable
mfa_unavailable503POST /v1/auth/login/mfa
microsoft_code_expired410POST /v1/setup/microsoft/finish
missing_field400POST /v1/tokens, POST /v1/warehouses, PATCH /v1/warehouses/{warehouse_id}, POST /v1/tables, PATCH /v1/table, DELETE /v1/table and 7 more
name_is_a_catalog409POST /v1/orgs/{org_id}/sources
name_reserved_until_cdn_purge409POST /v1/warehouses
name_reserved_until_purge409POST /v1/warehouses
name_reserved_until_teardown409POST /v1/warehouses
name_too_long_for_bucket400POST /v1/warehouses
namespace_not_empty409DELETE /v1/namespace
namespace_not_found404PUT /v1/warehouses/{warehouse_id}/grants/{principal_id}, GET /v1/tables, GET /v1/table, PATCH /v1/table, DELETE /v1/table, DELETE /v1/namespace and 1 more
news_disabled409PUT /v1/me/news
no_address409POST /v1/auth/google/reauth/email-code
no_domain_offer404POST /v1/orgs/{org_id}/join
no_key409POST /v1/sinks/{sink_id}/dedupe
no_organisation400DELETE /v1/warehouses/{warehouse_id}/grants/{principal_id}, PUT /v1/warehouses/{warehouse_id}/org-access
no_passkey409POST /v1/auth/passkeys/confirm/start, POST /v1/auth/passkeys/register/start
no_password_set409POST /v1/auth/password/change
no_pending_code404POST /v1/auth/google/link, POST /v1/auth/google/reauth/email-code/confirm
no_pending_signup404POST /v1/signup/verify
no_verified_domain400PATCH /v1/orgs/{org_id}
not_a_person403DELETE /v1/orgs/{org_id}, POST /v1/auth/google/reauth, POST /v1/auth/google/reauth/email-code, POST /v1/auth/reauth, POST /v1/auth/passkeys/confirm/start, GET /v1/auth/passkeys and 3 more
not_agent_manager403PATCH /v1/artifacts/{artifact_id}
not_an_array400POST /v1/sinks/{sink_id}
not_connection_owner403PUT /v1/orgs/{org_id}/connections/{name}/secret, DELETE /v1/orgs/{org_id}/connections/{name}, PUT /v1/orgs/{org_id}/connections/{name}/use-access, PUT /v1/orgs/{org_id}/connections/{name}/grants/{principal_id}, PUT /v1/orgs/{org_id}/connections/{name}/owner
not_deleted409POST /v1/warehouses/{warehouse_id}/restore
not_enabled403POST /v1/orgs/{org_id}/connections, POST /v1/orgs/{org_id}/sources, POST /v1/orgs/{org_id}/sources/{name}/refresh
not_found404POST /v1/sinks, GET /v1/object, POST /v1/query, GET /v1/auth/google/start, POST /v1/auth/google/callback, POST /v1/auth/google/reauth and 3 more
not_restorable409POST /v1/warehouses/{warehouse_id}/restore
not_unclaimed409DELETE /v1/agent/identity, POST /v1/agent/identity/claim
oauth_request_decided410GET /v1/oauth/authorize/pending
oauth_request_expired410GET /v1/oauth/authorize/pending, POST /v1/oauth/authorize/decision, GET /v1/oauth/authorize/set-up, POST /v1/oauth/authorize/set-up
oauth_request_not_found404GET /v1/oauth/authorize/pending, POST /v1/oauth/authorize/decision, GET /v1/oauth/authorize/set-up, POST /v1/oauth/authorize/set-up
operation_not_found404POST /v1/changes/operations/{operation_id}/restore
org_deleting409POST /v1/warehouses
org_has_members409DELETE /v1/orgs/{org_id}
org_not_found404POST /v1/projects, GET /v1/orgs/{org_id}/policy, DELETE /v1/orgs/{org_id}, GET /v1/audit
org_policy_forbids403POST /v1/warehouses/{warehouse_id}/public, DELETE /v1/warehouses/{warehouse_id}/public, POST /v1/orgs/{org_id}/connections, POST /v1/orgs/{org_id}/tokens, POST /v1/auth/device/approve, POST /v1/auth/cli/authorize and 5 more
org_required400, 409POST /v1/projects, GET /v1/oauth/authorize/pending, POST /v1/oauth/authorize/decision
origin_not_allowed403GET /v1/auth/google/start, POST /v1/auth/google/reauth, POST /v1/auth/google/reauth/email-code, POST /v1/auth/login/passkey, POST /v1/auth/refresh, POST /v1/auth/logout and 1 more
parts_mismatch409POST /v1/warehouses/{warehouse_id}/blobs/multipart/complete
passkey_exists409POST /v1/auth/passkeys/register/finish
passkey_limit409POST /v1/auth/passkeys/register/start, POST /v1/auth/passkeys/register/finish
passkey_not_found404DELETE /v1/auth/passkeys/{passkey_id}
passkeys_disabled403POST /v1/auth/login/passkey/start, POST /v1/auth/passkeys/confirm/start
password_login_disabled401, 403403 on any route except /v1/auth/*, for an address an organisation's provider covers, whose organisation does not enforce single sign-on, on a deployment with the ENS security profile; the sign-in and refresh routes answer it too (401 on a refresh), and the password routes answer it when this deployment turns password login off (Authentication), and POST /v1/auth/signup, POST /v1/auth/login, POST /v1/auth/device
password_reauth_required409POST /v1/auth/google/reauth, POST /v1/auth/google/reauth/email-code
password_required400, 409POST /v1/auth/reauth, POST /v1/auth/passkeys/register/start, POST /v1/auth/mfa/totp/start, POST /v1/setup, DELETE /v1/me
password_too_short400POST /v1/auth/password/set
person_required403PUT /v1/warehouses/{warehouse_id}/grants/{principal_id}, POST /v1/warehouses/{warehouse_id}/public, PATCH /v1/orgs/{org_id}/brand, DELETE /v1/orgs/{org_id}/brand, PUT /v1/orgs/{org_id}/brand/logo, DELETE /v1/orgs/{org_id}/brand/logo
prefix_overlaps409POST /v1/sql/connections
preview_empty409POST /v1/changes/{change_id}/restore
principal_inactive409PUT /v1/warehouses/{warehouse_id}/grants/{principal_id}
principal_not_found404PUT /v1/warehouses/{warehouse_id}/grants/{principal_id}, PUT /v1/orgs/{org_id}/connections/{name}/grants/{principal_id}, PUT /v1/orgs/{org_id}/connections/{name}/owner, PUT /v1/orgs/{org_id}/sources/{name}/grants/{principal_id}
principal_suspended403POST /v1/tokens, POST /v1/auth/login, POST /v1/auth/mfa/enrol/start, POST /v1/auth/login/passkey
project_not_empty409DELETE /v1/projects/{project_id}
project_not_found404GET /v1/projects/{project_id}, PATCH /v1/projects/{project_id}, DELETE /v1/projects/{project_id}, POST /v1/warehouses, GET /v1/warehouses
provisioning503POST /v1/query, GET /v1/connection
public_artifact_not_found404POST /v1/a/{artifact_id}/open, GET /v1/a/{artifact_id}/card, GET /v1/a/{artifact_id}/image, GET /v1/a/{artifact_id}/brand-logo, POST /v1/a/{artifact_id}/report
public_artifacts_not_enabled403PATCH /v1/artifacts/{artifact_id}
public_catalog409DELETE /v1/table, DELETE /v1/namespace
public_catalog_ambiguous409GET /v1/public/{handle}/{catalog}/connection
public_catalog_not_found404GET /v1/public/{handle}/{catalog}/connection
public_mail_domain400POST /v1/orgs/{org_id}/domains
public_reader_unavailable503GET /v1/public/{handle}/{catalog}/connection
query_timeout408POST /v1/query
query_unavailable503GET /v1/object
quota_exceeded409POST /v1/projects, POST /v1/warehouses, POST /v1/warehouses/{warehouse_id}/blobs/multipart, POST /v1/warehouses/{warehouse_id}/blobs/multipart/parts, POST /v1/warehouses/{warehouse_id}/public, POST /v1/tables and 3 more
rate_limited429POST /v1/tokens, POST /v1/signup/start, POST /v1/agent/identity, POST /v1/agent/identity/claim, GET /v1/handles/{handle}, POST /v1/signup/verify and 51 more
read_recipe_unavailable409GET /v1/connection
read_session_not_offered403POST /v1/credentials
reauth_not_fresh401POST /v1/auth/google/reauth
reauth_required401PATCH /v1/orgs/{org_id}/policy, PATCH /v1/orgs/{org_id}/members/{member_id}, DELETE /v1/orgs/{org_id}, POST /v1/orgs/{org_id}/invitations, POST /v1/orgs/{org_id}/tokens, PATCH /v1/orgs/{org_id}/tokens/{token_id} and 4 more
recovery_retired410POST /v1/recover/start, POST /v1/recover/verify
refresh_raced401POST /v1/auth/refresh
registration_closed403POST /v1/signup/start, POST /v1/agent/identity, POST /v1/signup/verify, POST /v1/signup, POST /v1/auth/signup, POST /v1/auth/password/set and 2 more
reserved_name400POST /v1/orgs/{org_id}/sources
role_from_group_rule409PATCH /v1/orgs/{org_id}/members/{member_id}
run_already_queued409POST /v1/sinks/{sink_id}/run
sandbox_token_mcp_only403POST /v1/sandbox-token
schema_changed409PATCH /v1/table
scoped_grants_held409PUT /v1/warehouses/{warehouse_id}/org-access
search_too_long400GET /v1/tables
service_account_data_only403POST /v1/warehouses
service_auth_not_enabled400POST /v1/agent/identity
session_ended401POST /v1/auth/google/reauth, POST /v1/auth/google/reauth/email-code/confirm
session_not_found404DELETE /v1/auth/sessions/{session_id}
session_required403POST /v1/auth/google/reauth, POST /v1/auth/google/reauth/email-code, POST /v1/auth/reauth, POST /v1/auth/passkeys/confirm/start, GET /v1/auth/passkeys, POST /v1/auth/passkeys/register/start and 8 more
setup_done409POST /v1/setup/microsoft/start, POST /v1/setup/microsoft/finish, POST /v1/setup
setup_handle_unknown404POST /v1/setup/microsoft/finish
several_organisations409DELETE /v1/me
sink_disabled409POST /v1/sinks/{sink_id}, POST /d/{token}
sink_exists409POST /v1/sinks, PATCH /v1/sinks/{sink_id}, POST /v1/indexes
sink_needs_read400POST /v1/orgs/{org_id}/tokens
sink_not_active409POST /v1/sinks/{sink_id}/dedupe
sink_not_found404GET /v1/sinks/{sink_id}, DELETE /v1/sinks/{sink_id}, POST /v1/sinks/{sink_id}, POST /v1/sinks/{sink_id}/test, POST /v1/sinks/{sink_id}/device-token, DELETE /v1/sinks/{sink_id}/device-token and 2 more
source_not_found404GET /v1/orgs/{org_id}/sources/{name}, DELETE /v1/orgs/{org_id}/sources/{name}, POST /v1/orgs/{org_id}/sources/{name}/refresh, GET /v1/orgs/{org_id}/sources/{name}/tables, PUT /v1/orgs/{org_id}/sources/{name}/org-access, PUT /v1/orgs/{org_id}/sources/{name}/grants/{principal_id}
source_unavailable502POST /v1/orgs/{org_id}/sources/{name}/refresh
sources_unavailable503POST /v1/orgs/{org_id}/sources/{name}/refresh
sso_renewal_required401any authenticated route, with an identity provider's token older than its organisation's session_max_hours (counted from the sign-in's auth_time, the ID token's included), and at the refresh of a Google Workspace session past it; it names the provider, login_hint and how to sign in again without a screen (prompt=none) (Authentication)
sso_required403any authenticated route, when the organisation's provider enforces single sign-on and the session was not made by it, or the token is another issuer's (Authentication), and POST /v1/signup/start, POST /v1/auth/signup
storage_error502, 503POST /v1/warehouses, POST /v1/warehouses/{warehouse_id}/measure, PUT /v1/warehouses/{warehouse_id}/grants/{principal_id}, POST /v1/warehouses/{warehouse_id}/uploaders, POST /v1/sinks/{sink_id}, POST /d/{token} and 13 more
storage_unmeasured503POST /v1/auth/device/approve
store_error502GET /v1/object
store_timeout504GET /v1/object
subscribers_full409POST /v1/a/{artifact_id}/subscribe
table_has_sinks409DELETE /v1/table, DELETE /v1/namespace
table_not_found404POST /v1/indexes, GET /v1/table, PATCH /v1/table, DELETE /v1/table, POST /v1/credentials, POST /v1/agents
terms_required400POST /v1/signup/verify, POST /v1/auth/google/callback, POST /v1/auth/google/signup, POST /v1/oauth/authorize/set-up, POST /v1/onboard
terms_version_mismatch409POST /v1/terms/accept
tier_policy_fixed409PATCH /v1/warehouses/{warehouse_id}
token_expired410POST /v1/auth/password/set, POST /v1/auth/password/reset
token_not_found404GET /v1/orgs/{org_id}/tokens/{token_id}, PATCH /v1/orgs/{org_id}/tokens/{token_id}, DELETE /v1/orgs/{org_id}/tokens/{token_id}
token_revoked401POST /v1/sandbox-token
too_large413PUT /v1/warehouses/{warehouse_id}/lifecycle, PUT /v1/warehouses/{warehouse_id}/agents-md, PUT /v1/orgs/{org_id}/brand/logo
too_many_claims400POST /v1/orgs/{org_id}/domains
unauthorized401GET /v1/public/{handle}/{catalog}/connection
unclaimed_expired401POST /v1/agent/identity/claim
unknown_field400PATCH /v1/projects/{project_id}, PATCH /v1/api-keys/{key_id}
unreadable_body400POST /d/{token}, POST /v1/sinks/{sink_id}/test
unsupported_engine400GET /v1/connection
unsupported_file_type415POST /v1/warehouses/{warehouse_id}/blobs/multipart
unsupported_media_type415POST /d/{token}, POST /v1/sinks/{sink_id}/test
unsupported_placement400POST /v1/projects
verification_required403POST /v1/signup
warehouse_deleted404DELETE /v1/warehouses/{warehouse_id}
warehouse_deleting404GET /v1/warehouses/{warehouse_id}
warehouse_not_found404GET /v1/warehouses/{warehouse_id}, PATCH /v1/warehouses/{warehouse_id}, POST /v1/warehouses/{warehouse_id}/measure, GET /v1/warehouses/{warehouse_id}/grants, GET /v1/warehouses/{warehouse_id}/org-access, PUT /v1/warehouses/{warehouse_id}/org-access and 34 more
watch_needs_read400POST /v1/agents
watch_own_write400POST /v1/agents
workspace_reauth_required409POST /v1/auth/google/reauth/email-code