Common errors
Diagnose authentication, authorization, validation, idempotency, rate, and dependency failures.
Start with the HTTP status, error.code, and correlationId. Preserve the correlation ID before retrying; it connects the client failure to content-free server diagnostics.
401 unauthenticated
Confirm the request uses Authorization: Bearer ..., the token has no surrounding quotes or whitespace, and the base URL is the intended deployment. Human tokens can expire; agent credentials can be revoked. Obtain a fresh credential instead of repeatedly retrying. For MCP, allow the client to follow the advertised OAuth metadata.
403 forbidden
The token is valid but the principal lacks the requested Account role, Source grant, dataset grant, or management capability. Verify the Account with GET /v1/accounts, then inspect Access. Do not try random Account or Source IDs: hidden resources intentionally remain undisclosed.
404 not_found
Check that the UUID belongs to the specified Account and is visible to the principal. A deleted Source and a Source outside the principal's scope can both be unavailable. Refresh the catalogue rather than retaining identifiers indefinitely.
409 conflict
For idempotency conflicts, confirm the key was reused only with the identical method, operation, principal, and body. If the operation is still in progress, inspect Activity or the resource status before retrying with the same key. Other conflicts usually mean the resource state changed since the UI or client read it.
413 payload_too_large
Keep the request below the documented boundary. Reduce arrays, query text, and requested output. A worker payload failure can also mean selected columns or values are too large; project fewer columns, filter earlier, and lower maxRows.
422 bad_request or query_rejected
Read details.issues for field paths. For SQL, refresh the catalogue, use one read-only SELECT, remove unsupported statements/functions, parameterize values, and make limits explicit. A query can also be rejected by the Source/dataset grant or byte bound.
429 rate_limited or limit_reached
Honor Retry-After. Reduce concurrency and request size, then retry with bounded backoff. Monthly Account budget, per-grant query rate, concurrent query admission, and returned-row/input-byte limits are separate controls; the error details and Usage view identify the relevant one.
500 internal_error or 503 temporarily_unavailable
For 503, honor Retry-After and retry a GET with bounded backoff. Do not blindly repeat a mutation or SQL request: use its original idempotency key and inspect status first. For a repeatable 500, capture safe diagnostics and contact support with the correlation ID.
See the REST error contract for the full status and code list.