Handle Failures

A failed RPC Exit becomes EffectRpcQueryError. The error records the RPC tag, the generated operation that ran, and the complete Effect Cause:

import { Cause } from 'effect'
import { isEffectRpcQueryError } from 'effect-api-query'

const logRpcError = (error: unknown) => {
  if (isEffectRpcQueryError(error)) {
    console.error(error.rpcTag, error.operation)
    console.error(Cause.pretty(error.cause))
  }
}

These error classes distinguish failure stages:

• EffectRpcQueryConfigError reports invalid factory or builder configuration synchronously.
• EffectRpcQueryKeyError reports synchronous payload construction, encoding, or JSON canonicalization failures.
• EffectRpcQueryError reports a failed RPC execution and preserves its Effect Cause.
• EffectRpcQueryEmptyStreamError reports a live stream that completed before emitting a value.

If a custom runner rejects instead of returning an Exit, its rejection passes through unchanged. See the error reference for stable codes and metadata.

Inspect HTTP failures

Import isEffectHttpApiQueryError from effect-api-query to recognize a failed HTTP execution. The wrapper identifies apiId, groupId, endpoint, method, and operation, and its cause retains the complete original Effect Cause. Use Cause.findError to inspect declared endpoint errors, middleware errors, Schema errors, and HTTP client errors. Use Cause.hasDies and Cause.hasInterrupts to distinguish defects and interruption. A Cause may contain several reasons.

The package adds only declaration identity to execution-error metadata. The preserved Cause can contain upstream request headers, bodies, concrete URLs, responses, or Schema issue values. Review those values before logging or exposing them. The package does not sanitize the Cause.

EffectHttpApiQueryConfigError reports invalid factory configuration synchronously. EffectHttpApiQueryKeyError reports synchronous query-key preparation failures, before HTTP execution. Mutations encode their request inside the ready client’s Effect, so encoding failures become EffectHttpApiQueryError instead. Runner rejections and user or TanStack callback failures pass through unchanged when they produce no failed Exit.

See the HTTP factory reference for key-error codes.

The packed RPC consumer and packed HTTP consumer verify error guards and preserved Causes.