Errors
Error envelope, public codes, HTTP status meanings, and safe recovery behavior.
All REST errors use one envelope:
{
"error": {
"code": "query_rejected",
"message": "Only one read-only SELECT is accepted.",
"correlationId": "cor_01K2A000000000000000000101",
"details": {}
}
}details is optional and machine-readable. For request validation it can contain an issues array with field paths. Do not parse the human message to make program decisions; branch on HTTP status and code.
HTTP status guide
| Status | Meaning | Caller action |
|---|---|---|
400 | Invalid JSON or malformed request | Correct serialization; do not retry unchanged. |
401 | Missing, expired, invalid, or revoked credential | Reauthenticate or rotate the credential. |
403 | Principal lacks the required Account capability or grant | Ask an authorized owner/deployer for the narrow grant. |
404 | Visible resource does not exist | Verify account and identifier; hidden resources are not disclosed. |
409 | State or idempotency conflict | Inspect state; reuse a key only with the identical request. |
413 | Body or query-worker payload bound exceeded | Reduce the request or result shape. |
422 | Structurally valid request failed validation or query policy | Use details, catalogue, and SQL rules to correct it. |
429 | Rate, concurrency, budget, or grant limit reached | Honor Retry-After; narrow or defer work. |
500 | Unexpected server failure | Preserve correlation ID and contact support if repeatable. |
503 | Required dependency temporarily unavailable | Honor Retry-After and use bounded backoff. |
Public error codes
The stable contract includes bad_request, unauthenticated, forbidden, not_found, conflict, rate_limited, limit_reached, needs_authorization, needs_review, query_rejected, query_timeout, invalid_credentials, payload_too_large, temporarily_unavailable, and internal_error. A more specific code may be returned as a capability evolves; clients should preserve unknown strings and still use the HTTP class.
needs_authorization means the Source must be authorized again. needs_review means a schema decision is required. query_rejected means SQL, relation scope, or a grant bound failed before a successful result. query_timeout is not proof that the request never started; inspect the query receipt when available.
Safe diagnostic report
Record the UTC time, HTTP status, error code, correlation ID, operation ID or method/path, SDK version, and whether the request was a retry. Redact bearer tokens, provider credentials, SQL literal values, returned rows, and private Source content. See Safe diagnostics.