Handle the shared error envelope and use request IDs for tracing and support.
API errors use one envelope:
{
"detail": {
"message": "Workspace role 'editor' or higher is required.",
"code": "insufficient_workspace_role",
"hint": "Ask a workspace admin to update your role or perform this action.",
"request_id": "4acfd42a-2c02-4ed7-8f74-95196664988e"
}
}| Field | Meaning |
|---|---|
message | Human-readable explanation. |
code | Stable machine-readable code. Always present. |
hint | Optional safe next step, or null. |
request_id | Identifier for logs and support. Matches the x-request-id header. |
Some errors add fields, such as errors on validation failures, query on warehouse query failures, or candidates (fully qualified table names to try) when a short table name is ambiguous or not found. Extra fields are additive and may change. SCIM routes under /scim/v2 use the SCIM error schema instead.
Every product API response echoes an x-request-id header. You may supply your own x-request-id; otherwise Embrasure creates one. Analytics collection always generates its own.
curl --header "x-request-id: deploy-842-sync" ...| Status | Meaning |
|---|---|
400 | Malformed request or identifier. |
401 | Missing, malformed, expired, or revoked token. |
402 | The workspace's plan does not include the feature or allowance. |
403 | Scope, workspace role, or workspace authorization failure. |
404 | The resource does not exist or is not visible to the caller. |
409 | Conflict with current state, such as a resource in use, a duplicate, or a reused request identifier. |
410 | The resource has expired, such as stored query results. |
413 | Request size limit. |
422 | Request validation failed; errors lists each invalid field. |
429 | Rate limit, quota, or safety limit. See rate limits. |
5xx | Service failure. Retry with backoff. |
When an endpoint has no more specific code, code is derived from the status: bad_request, unauthorized, forbidden, not_found, conflict, gone, payload_too_large, validation_error, rate_limited, internal_error, bad_gateway, service_unavailable, or gateway_timeout. All authentication failures use unauthorized; read message for the reason.
| Code | Meaning |
|---|---|
insufficient_scope | 403: the token lacks the required scope. Reconnect or create a token with that scope. |
insufficient_workspace_role | 403: the caller's workspace role does not permit the action. |
workspace_token_mismatch | 403: the request's workspace_id is not the token's workspace. |
personal_access_tokens_disabled | 403: personal access tokens are turned off for the workspace. |
sso_required | 403: the workspace requires SSO, so personal access tokens are rejected. |
token_write_database_limited | 403: the token can write only to specific warehouse databases. |
validation_error | 422: the request body or query failed validation. |
invalid_request_identifier | 400: an identifier in the path or query is malformed. |
client_request_id_conflict | 409: the request identifier was already used for a different request. |
warehouse_invalid_query | 400: the SQL could not be planned. See the SQL reference. |
warehouse_sql_* | 400: the SQL or a table name was rejected before running, for example warehouse_sql_parse_error, warehouse_sql_multiple_statements, warehouse_sql_relation_ambiguous, or warehouse_sql_relation_not_found. hint and candidates suggest the fully qualified name. |
warehouse_access_denied | 403: the warehouse denied the query. |
warehouse_rate_limited | 429: the warehouse is throttling queries. Retry with backoff. |
warehouse_results_expired | 410: stored results passed their seven-day retention. Run the query again. |
warehouse_query_failed | 502: the query failed in the warehouse. |
source_rate_limited | 429: the source is pacing requests. Retry after Retry-After; background syncs resume automatically. |
connector_preflight_rate_limited | 429: five connection checks were already attempted in the current ten-minute window. |
request_rate_limited | 429: the token or workspace exceeded its per-minute request limit. Retry after Retry-After. |
chat_rate_limited | 429: too many questions were started in the last minute. Retry after Retry-After. |
plan_feature_unavailable | 402: the workspace's plan does not include the feature. |
plan_ai_credits_exhausted | 402: the workspace used its monthly AI credits. |
plan_scan_allowance_exhausted | 402: the workspace used its monthly query scan allowance. |
plan_source_limit_reached | 402: the workspace already has its plan's number of sources. Sample data, removed sources, and abandoned sign-ins do not count. |
plan_storage_limit_reached | 402: the workspace is at its managed storage allowance. |
workspace_daily_scan_cap_reached | 429: the workspace reached its daily safety limit on data scanned. Resets at 00:00 UTC. |
workspace_daily_spend_cap_reached | 429: the workspace reached its daily safety limit on AI and query compute. Resets at 00:00 UTC. |
workspace_monthly_spend_cap_reached | 429: the workspace reached its monthly safety limit on AI and query compute. Resets on the 1st (UTC). |
workspace_daily_ingestion_cap_reached | 429: the workspace reached its daily ingestion safety limit. Syncs resume after 00:00 UTC. |
Safety-limit and quota responses do not include Retry-After; hint describes when the limit resets.
A query that was accepted but failed later reports its reason in the query's error_code rather than as an HTTP error. Two common values are warehouse_query_timeout, when the query ran past its timeout, and warehouse_scan_cap_exceeded, when it tried to scan more than 25 GiB.
See troubleshooting for fixes and limits for allowances.