API Response Codes

Table of Contents

Success Responses
Error Types
REST Error Payload
GraphQL Error Format
Error Components
Correlating Errors with Performance Logs

All Kloudfuse query APIs — metrics, logs, traces, events, RUM, and LLM — use one standardized set of response codes and error payloads. A failed REST call returns a JSON error payload with a meaningful HTTP status code, and a failed GraphQL operation returns the same information in the standard GraphQL errors field. The same failure is recorded on the performance log line for the call; when a REST response carries a request_id, it links the response to that log entry directly. See Performance Log Fields.

This page covers the query APIs: the Prometheus-compatible metrics API, the Loki-compatible logs API, the Tempo-compatible traces API, and the GraphQL APIs served at /query. The Ingester, Folders, Policies, Teams, and Hydration APIs return their own service-specific responses.

Error messages returned to the caller are deliberately safe and generic. Internal diagnostic detail — hostnames, data store error text, policy scopes — never appears in an API response; it is recorded only in the error_detail facet of the performance log entry for that request.

Success Responses

A successful REST call returns HTTP 200 with the response body documented on that API’s reference page. A successful GraphQL request also returns HTTP 200, with the result in the data field and no errors field.

HTTP 200 alone does not mean a GraphQL operation succeeded: a failed operation also answers 200, with the failure in the errors field. GraphQL clients must check for errors in the body; see GraphQL Error Format.

Error Types

Every failure is classified as one of ten error types. The type appears as errorType in REST responses, as extensions.errorType in GraphQL errors, and as the error_type facet in performance logs. For REST calls it determines the HTTP status code.

Error type HTTP status Meaning

Error type	HTTP status	Meaning
`BAD_REQUEST`	400	The request is invalid: a malformed query expression, a bad parameter, or a limit exceeded by the request itself. Fix the request before retrying.
`UNAUTHORIZED`	401	The request carried no valid authentication. Supply a valid session or Service Account token.
`FORBIDDEN`	403	The caller is authenticated but RBAC policy denies access to the requested data.
`NOT_FOUND`	404	The requested resource does not exist.
`RESOURCE_EXHAUSTED`	422	The query exceeded data store resource limits. Narrow the time range or add filters, then retry.
`RATE_LIMITED`	429	Too many queries are in flight or the data store is at capacity. Retry shortly.
`CANCELED`	499	The caller closed the connection before the response was complete.
`INTERNAL_ERROR`	500	An unexpected failure inside Kloudfuse. Not caused by the request; report it if it persists.
`SERVICE_UNAVAILABLE`	503	A component the query depends on is temporarily unavailable, restarting, or missing data. Transient; retry shortly.
`TIMEOUT`	504	The query did not complete within its time budget. Retry, or narrow the time range if it recurs.

BAD_REQUEST

400

The request is invalid: a malformed query expression, a bad parameter, or a limit exceeded by the request itself. Fix the request before retrying.

UNAUTHORIZED

401

The request carried no valid authentication. Supply a valid session or Service Account token.

FORBIDDEN

403

The caller is authenticated but RBAC policy denies access to the requested data.

NOT_FOUND

404

The requested resource does not exist.

RESOURCE_EXHAUSTED

422

The query exceeded data store resource limits. Narrow the time range or add filters, then retry.

RATE_LIMITED

429

Too many queries are in flight or the data store is at capacity. Retry shortly.

CANCELED

499

The caller closed the connection before the response was complete.

INTERNAL_ERROR

500

An unexpected failure inside Kloudfuse. Not caused by the request; report it if it persists.

SERVICE_UNAVAILABLE

503

A component the query depends on is temporarily unavailable, restarting, or missing data. Transient; retry shortly.

TIMEOUT

504

The query did not complete within its time budget. Retry, or narrow the time range if it recurs.

SERVICE_UNAVAILABLE, RATE_LIMITED, and TIMEOUT failures are transient and safe to retry. BAD_REQUEST and RESOURCE_EXHAUSTED require changing the request first.

REST Error Payload

REST endpoints — the Prometheus-compatible metrics API, the Loki-compatible logs API, the Tempo-compatible traces API, and the other REST endpoints — return errors as Content-Type: application/json with the HTTP status from the table above and this body:

{
  "status": "error",
  "errorType": "SERVICE_UNAVAILABLE",
  "error": "Some data is temporarily unavailable",
  "request_id": "d5bf9448-3c7a-4a56-9f2e-8a1b2c3d4e5f"
}

json

Field Description

Field	Description
`status`	Always the literal string `error`.
`errorType`	One of the ten error types.
`error`	Human-readable message describing the failure.
`request_id`	Identifier of the failed request. Matches the `kf_request_id` facet on the performance log lines for the same call. Omitted when no request identifier is available.

status

Always the literal string error.

errorType

One of the ten error types.

error

Human-readable message describing the failure.

request_id

Identifier of the failed request. Matches the kf_request_id facet on the performance log lines for the same call. Omitted when no request identifier is available.

The payload follows the Prometheus error-response convention (status, errorType, error), so Grafana and other Prometheus-compatible clients render the message instead of a bare HTTP status.

GraphQL Error Format

GraphQL queries and mutations return HTTP 200 even when they fail; the failure is reported in the standard errors field of the response body. Subscriptions run over a WebSocket connection, so there is no HTTP status at all: a failed subscription delivers an error message on the stream carrying the same fields. Each error entry carries the message, the path of the operation that failed, and an extensions object with the same standardized classification as REST responses:

{
  "errors": [
    {
      "message": "Query timed out",
      "path": ["getLogMetricsResultWithKfuseQl"],
      "extensions": {
        "component": "pinot",
        "errorType": "TIMEOUT"
      }
    }
  ],
  "data": null
}

json

Field Description

Field	Description
`message`	Human-readable message describing the failure. Same content as the REST `error` field.
`path`	GraphQL path of the field that failed. Present when a resolver failed; absent when the request was rejected before execution, for example on a malformed document.
`extensions.component`	Which component the failure originated in.
`extensions.errorType`	One of the ten error types. GraphQL does not convey the failure through a transport status code, so this field is how a client distinguishes a timeout from an internal failure.

message

Human-readable message describing the failure. Same content as the REST error field.

path

GraphQL path of the field that failed. Present when a resolver failed; absent when the request was rejected before execution, for example on a malformed document.

extensions.component

Which component the failure originated in.

extensions.errorType

One of the ten error types. GraphQL does not convey the failure through a transport status code, so this field is how a client distinguishes a timeout from an internal failure.

This format applies to queries, mutations, and subscriptions alike. A malformed GraphQL document is rejected as BAD_REQUEST with the validation message describing what is wrong with the document.

Error Components

The component identifies where a failure originated. It appears as extensions.component in GraphQL errors and as the error_component facet in performance logs.

Component Origin of the failure

Component	Origin of the failure
`query-service`, `logs-query-service`, `trace-query-service`, `events-query-service`, `rum-query-service`, `llm-query-service`	The query service handling the call. Used for failures the service itself decided or detected: invalid input, an authentication or authorization denial, or the service’s own query time budget expiring.
`pinot`	The telemetry data store. Data store error codes are translated into the standardized error types with safe messages; a data store failure is never reported as `BAD_REQUEST`.
`postgres`	The configuration database.
`redis`	The cache.
`kafka`	The ingestion message bus.
`ums`	The user management service, which serves authentication and RBAC data.
`advanced-functions`	The analytics service that evaluates advanced functions.

query-service, logs-query-service, trace-query-service, events-query-service, rum-query-service, llm-query-service

The query service handling the call. Used for failures the service itself decided or detected: invalid input, an authentication or authorization denial, or the service’s own query time budget expiring.

pinot

The telemetry data store. Data store error codes are translated into the standardized error types with safe messages; a data store failure is never reported as BAD_REQUEST.

postgres

The configuration database.

redis

The cache.

kafka

The ingestion message bus.

ums

The user management service, which serves authentication and RBAC data.

advanced-functions

The analytics service that evaluates advanced functions.

Correlating Errors with Performance Logs

Every error returned by an API is also recorded on the Finished API performance log line for the call, in the is_error, error_type, error_component, error_user_msg, and error_detail facets. The error_user_msg facet carries the exact message the caller received, and error_detail carries the internal diagnostic detail that is withheld from the response.

To find the log entry for a failed call, filter on the request_id from the REST error payload:

@perf_log="true" and @msg="Finished API" and @kf_request_id="d5bf9448-3c7a-4a56-9f2e-8a1b2c3d4e5f"

text

See Performance Log Fields for the full field reference and Query Examples for error-rate and latency queries over these fields.