http/jsonrpc_errors.ts

JSON-RPC error infrastructure for fuz_app routes.

Provides error types, named constructors, and HTTP status mapping for the throw/catch error pattern used by apply_route_specs. Core error codes (5 standard + 10 general application). Domain-specific codes stay in consumers — add by casting as JsonrpcErrorCode.

JsonrpcErrorCode and JsonrpcErrorObject types are Zod-inferred from http/jsonrpc.ts — this module re-uses those as the single source of truth.

Complementary to http/error_schemas.ts: that module is declarative (Zod schemas for surface introspection), this one is runtime (throw + catch + map).

Declarations
#

10 declarations

view source

http_status_to_jsonrpc_error_code
#

http/jsonrpc_errors.ts view source

(status: number): -32700 | -32600 | -32601 | -32602 | -32603 | (number & $brand<"JsonrpcServerErrorCode">)

Map an HTTP status code to a JSON-RPC error code.

Returns internal_error (-32603) for unrecognized status codes.

status

type number

returns

-32700 | -32600 | -32601 | -32602 | -32603 | (number & $brand<"JsonrpcServerErrorCode">)

HTTP_STATUS_TO_JSONRPC_ERROR_CODE
#

http/jsonrpc_errors.ts view source

Record<number, -32700 | -32600 | -32601 | -32602 | -32603 | (number & $brand<"JsonrpcServerErrorCode">)>

Maps HTTP status codes to JSON-RPC error codes (reverse mapping).

When multiple error codes map to the same HTTP status (e.g. parse_error and invalid_request both map to 400), the last one wins. Use for best-effort HTTP → JSON-RPC translation.

jsonrpc_error_code_to_http_status
#

http/jsonrpc_errors.ts view source

(code: -32700 | -32600 | -32601 | -32602 | -32603 | (number & $brand<"JsonrpcServerErrorCode">)): number

Map a JSON-RPC error code to an HTTP status code.

Returns 500 for unrecognized codes (consumer-defined codes without a mapping default to internal server error).

code

type -32700 | -32600 | -32601 | -32602 | -32603 | (number & $brand<"JsonrpcServerErrorCode">)

returns

number

JSONRPC_ERROR_CODE_TO_HTTP_STATUS
#

http/jsonrpc_errors.ts view source

Record<number, number>

Maps JSON-RPC error codes to HTTP status codes.

Extensible — consumers with domain-specific error codes assign directly (JSONRPC_ERROR_CODE_TO_HTTP_STATUS[-32020] = 502) at module load. The lookup function reads at call time, so mutation is the supported extension mechanism.

JSONRPC_ERROR_CODES
#

http/jsonrpc_errors.ts view source

Readonly<Record<JsonrpcErrorName, -32700 | -32600 | -32601 | -32602 | -32603 | (number & $brand<"JsonrpcServerErrorCode">)>>

Standard JSON-RPC error codes (5) plus general application codes (10).

Extensible — consumers add domain-specific codes to their own objects by casting as JsonrpcErrorCode. Application codes use the -32000 to -32099 range reserved by the JSON-RPC spec.

Frozen with Object.freeze to convert accidental mutation (test cross-contamination, cast escapes) into loud TypeErrors. Spread into a fresh object to extend.

jsonrpc_error_messages
#

http/jsonrpc_errors.ts view source

Readonly<Record<JsonrpcErrorName, (...args: any[]) => { [x: string]: unknown; code: -32700 | -32600 | -32601 | -32602 | -32603 | (number & $brand<"JsonrpcServerErrorCode">); message: string; data?: unknown; }>>

Named constructors for JsonrpcErrorObject values.

Each function creates a JSON-RPC error object with the correct code and a sensible default message. Used by the catch layer in apply_route_specs to build response bodies.

Frozen so tests must compose new objects rather than monkey-patch.

jsonrpc_errors
#

http/jsonrpc_errors.ts view source

{ readonly parse_error: (...args: any[]) => ThrownJsonrpcError; readonly invalid_request: (...args: any[]) => ThrownJsonrpcError; readonly method_not_found: (...args: any[]) => ThrownJsonrpcError; ... 11 more ...; readonly request_cancelled: (...args: any[]) => ThrownJsonrpcError; }

Named constructors for ThrownJsonrpcError.

Usage: throw jsonrpc_errors.not_found('user') or throw jsonrpc_errors.forbidden().

JsonrpcErrorName
#

ThrownJsonrpcError
#

http/jsonrpc_errors.ts view source

Error class carrying a JSON-RPC error code — thrown by handlers, caught by apply_route_specs and mapped to HTTP status + JSON-RPC error response.

Named for what it is: an error with a JSON-RPC error code that gets thrown.

inheritance

extends:
  • Error

code

type JsonrpcErrorCode

data

type unknown

constructor

type new (code: -32700 | -32600 | -32601 | -32602 | -32603 | (number & $brand<"JsonrpcServerErrorCode">), message: string, data?: unknown, options?: ErrorOptions | undefined): ThrownJsonrpcError

code
type -32700 | -32600 | -32601 | -32602 | -32603 | (number & $brand<"JsonrpcServerErrorCode">)
message
type string
data?
type unknown
optional
options?
type ErrorOptions | undefined
optional

UNKNOWN_ERROR_MESSAGE
#

Depends on
#

Imported by
#