Skip to main content

Errors

Published endpoints answer errors as RFC 9457 problems (Content-Type: application/problem+json) with a stable code and the requestId of the call:

{
"type": "about:blank",
"title": "Bad Request",
"status": 400,
"detail": "Parameter 'tier' must be one of gold, silver, bronze.",
"code": "invalid_param",
"requestId": "4f1c9f0e-3a57-4d07-9a8e-2a1f1b0b6c11"
}

Program against status and code. The detail text is for people and may change. Server errors (5xx) keep their details in the server log and in Activity, found by requestId.

Calling endpoints​

StatusCodeMeaning
400invalid_paramA parameter is missing, has the wrong type, or breaks its constraints
400rule_failedA parameter rule does not hold; detail is the rule's message
400invalid_cursorThe after cursor is not one this endpoint issued
400invalid_bodyThe JSON body cannot be read
400bad_requestA full-mode script called badRequest(…)
401unauthenticatedA private endpoint was called without a token (WWW-Authenticate: Bearer realm="opendbapi")
401invalid_tokenThe token is malformed, expired, or its client was revoked or disabled
401bad_signatureThe client must sign requests and the signature is missing, stale, wrong or replayed
403not_grantedThe service account has no grant on this endpoint or its group
403ip_blockedThe workspace firewall refuses the caller's address
403missing_attributeA row filter needs an attribute the service account does not have
403row_filter_needs_clientA row filter applies, but the call has no client
403write_in_getA GET endpoint tried to change data
400transaction_unsupportedThe endpoint runs in a transaction, but its datasource (StarRocks, Apache Doris, ClickHouse) has none
403read_only_datasourceA query tried to change data on a read-only datasource
404not_foundNo published endpoint at this method and path, or a Single object endpoint found no row
406not_acceptableThe requested format is not allowed (streaming off, or an encrypted client asked for a stream)
413body_too_largeThe body is larger than 1 MB
415unsupported_media_typeThe body is not JSON
429rate_limitedA rate limit is exceeded; wait Retry-After seconds
500query_failedThe database refused the query
502upstream_failedAn HTTP API answered an error, a redirect or no JSON, or could not be reached
500script_failedA Groovy script failed
500workflow_failedA workflow node failed, or endpoints called each other too deep
500template_failedThe SQL template could not be rendered with these values
500row_filter_failed / keyset_failedThe filtered or paged query could not be built
503datasource_missingThe endpoint's datasource was deleted
503endpoint_unavailableThe endpoint cannot answer right now
504query_timeoutThe query took longer than the endpoint's timeout

Token endpoint​

POST /oauth2/token answers errors in the OAuth2 format, {"error": "…", "error_description": "…"}:

StatuserrorMeaning
400invalid_requestThe request is missing grant_type or the client credentials
400unsupported_grant_typeOnly client_credentials is supported
401invalid_clientUnknown client, wrong secret, or a revoked, expired or disabled client

Management API​

The management API (/admin/api) uses the same problem format. Codes you may meet when automating it:

StatusCodeMeaning
400invalid_endpoint, invalid_datasource, invalid_policy, …The request breaks a rule; detail says which
400not_a_databaseTables, schemas and columns were asked of an HTTP API datasource
400preview_cannot_roll_backPreview refused a statement that changes data on a database without transactions
409validation_failedPublishing found errors in the draft (bad SQL, writes in GET, an HTTP request on a database, …)
409config_lockedThe workspace is managed by configuration files
409nothing_to_publishThe saved draft equals the live version
409tests_failedPublishing requires passing tests and one failed
409route_taken / route_lockedAnother endpoint has this method and path / the path cannot change while live
409plan_changedapply --expected-digest no longer matches the plan
409datasource_in_use / secret_in_useStill used by endpoints / datasources or alert channels