Errors

Service API errors in RawTree Cloud and RawTree BYOC normally use this JSON body:

{
  "error": "not_found",
  "message": "The requested resource was not found.",
  "hint": "Check the resource identifier."
}

The JSON field is error, not code. Its value is the backend error code. The backend also attaches the code to structured request details.

The singular hint gives guidance for the failed API request. It can concern authentication, permissions, request syntax, or other errors. The plural hints in query results contains runtime type-compatibility warnings, which can accompany a successful query.

Other response formats

Some endpoints use a different error format:

• OAuth protocol errors use error and error_description, without hint.
• JSON table inserts without a transform can return the database's native HTTP status, body, and exception headers.
• Native app endpoints can use their protocol's error format. See OpenTelemetry, Prometheus, and Splunk.
• Streaming queries can report an exception after HTTP 200, or the connection can close before completion.

Check the endpoint's response format before parsing an error. For streaming queries, consume the complete response and check for exceptions.

Error codes

The following codes apply to the standard service error body.

bad_request

HTTP status: 400

Meaning: The request contains invalid input.

Common causes: A required parameter is missing, or a value fails route validation.

What to do: Correct the input. Follow the response message and hint.

request_body_incomplete

HTTP status: 400

Meaning: The server could not read the complete request body.

Common causes: The upload connection closed or the body ended before the server received it.

What to do: Check the upload connection and client timeout settings.

request_body_timeout

HTTP status: 408

Meaning: The server timed out while it read the request body.

Common causes: The client did not send the complete body before the upload deadline.

What to do: Send the complete request body within the upload deadline.

payload_too_large

HTTP status: 413

Meaning: A request body or formatted SQL output exceeds its size limit.

Common causes: A query body exceeds 50 MiB, a table-insert body exceeds 100 MiB, or formatted SQL exceeds 100 MiB.

What to do: Reduce the body size, split an insert, or format a smaller SQL selection. See Limits.

request_timeout

HTTP status: 408

Meaning: Query execution or SQL formatting exceeded its time limit.

Common causes: A query exceeded its effective max_execution_time, or SQL formatting exceeded 30 seconds.

What to do: Optimize the query or format a smaller SQL selection. Check the response hint for the effective timeout.

unprocessable_entity

HTTP status: 422

Meaning: The server received the content but could not process it.

Common causes: JSON fields have invalid data, or a PromQL query is unsupported.

What to do: Correct the content. Follow the response message and hint.

unauthorized

HTTP status: 401

Meaning: The request does not have valid authentication.

Common causes: The request has no valid API key or access token.

What to do: Send valid credentials in the Authorization header. Follow the response hint.

forbidden

HTTP status: 403

Meaning: The authenticated caller cannot perform the requested operation.

Common causes: The API key or database role does not have the required permission.

What to do: Check the key permission and database role grants named in the response hint.

payment_required

HTTP status: 402

Meaning: The organization's current billing state blocks the request.

Common causes: Trial credits are depleted or expired, the spending limit is reached, or the subscription is inactive.

What to do: Follow the response hint to update billing or the spending limit.

authorization_pending

HTTP status: 428

Meaning: The authorization flow is not complete.

Common causes: The user has not completed the pending authorization request.

What to do: Complete authorization, then retry the request. OAuth token endpoints use their own protocol errors and status codes.

service_unavailable

HTTP status: 503

Meaning: A service required for the request is unavailable.

Common causes: A dependent service is unavailable, the SQL formatter is busy, or an insert upload stops making progress.

What to do: Follow the response hint. Retry when the service is available.

cluster_paused

HTTP status: 409

Meaning: The cluster is paused and cannot serve data requests.

Common causes: The request targets a paused cluster.

What to do: Resume the cluster before sending data requests.

upstream_unavailable

HTTP status: 503

Meaning: No healthy cluster upstream is available.

Common causes: The cluster has no healthy upstream, or the service cannot reach the database.

What to do: Check cluster status. Retry when the cluster is ready.

not_found

HTTP status: 404

Meaning: The requested resource does not exist.

Common causes: A resource identifier does not match an existing resource.

What to do: Check the identifier and follow the response hint.

conflict

HTTP status: 409

Meaning: The request conflicts with the current resource state.

Common causes: The requested change is not valid for the resource's current state.

What to do: Follow the response message and hint, then resolve the conflict.

rawtree_error

HTTP status: 400

Meaning: RawTree rejected a query or database operation.

Common causes: SQL syntax is invalid, a table does not exist, a grant is missing, or the query result exceeds its size limit.

What to do: Correct the SQL or resource name. Check the database role grants when the response reports access denied.

internal_error

HTTP status: 500

Meaning: The server could not complete the request because of an internal error.

Common causes: An unexpected backend operation failed.

What to do: Try again or contact support.

rate_limit_exceeded

HTTP status: 429

Meaning: The request rate exceeds the limit for its endpoint.

Common causes: Too many queries share a database, or too many inserts target one table. OAuth endpoints also impose request-rate limits.

What to do: Wait for retry-after when present, then reduce the request rate. See rate-limit responses for query and insert headers. OAuth responses use error_description and can omit those headers.

Authentication challenges

Standard HTTP 401 responses include WWW-Authenticate: Bearer.

For OAuth authorization, the challenge can identify the protected resource metadata endpoint:

WWW-Authenticate: Bearer resource_metadata="https://api.rawtree.com/.well-known/oauth-protected-resource"

Retry behavior

An error or closed connection does not prove that a write had no effect. An insert can write rows before it fails, and timed-out distributed DDL can still finish. Check query history or the destination state before retrying a write. Use supported insert deduplication when retries must avoid duplicate rows.

Examples

This query returns a rawtree_error because the table does not exist:

SELECT * FROM missing_events

A query that names a missing column also returns a rawtree_error:

SELECT missing_column