ProblemDetails unstable

RFC 9457 Problem Details values for HTTP responses.

A problem details object is the application/problem+json body a server sends to describe an error. This module provides the reusable value shape, a lenient codec that follows the parsing rules of RFC 9457, and a response constructor. The effect/http-api modules build typed problem declarations, built-in error rendering and OpenAPI output on top of it.

6 exports Since v4.0.6 Source

Constants

blankType

unstable

Since v4.0.6

The problem type URI RFC 9457 assigns to problems that only carry an HTTP status.

Signature

declare const blankType: "about:blank"

contentType

unstable

Since v4.0.6

The media type of a problem details response body.

Signature

declare const contentType: "application/problem+json"

Constructors

toResponse

unstable

Since v4.0.6

Renders a problem details object as an application/problem+json response.

Details

The response status is the problem's status member, or 500 when it is absent.

Signature

declare function toResponse(problem: ProblemDetails): HttpServerResponse

Models

ProblemDetails

interface unstable

Since v4.0.6

A decoded RFC 9457 problem details object.

Details

The standard members are type, status, title, detail and instance. Any other member is an extension and is kept as-is.

Signature

interface ProblemDetails {
  [extension: string]: unknown;
  readonly detail?: string;
  readonly instance?: string;
  readonly status?: number;
  readonly title?: string;
  readonly type: string;
}

ProblemDetailsEncoded

interface unstable

Since v4.0.6

The encoded form of a problem details object, where type may be omitted.

Signature

interface ProblemDetailsEncoded {
  [extension: string]: unknown;
  readonly detail?: string;
  readonly instance?: string;
  readonly status?: number;
  readonly title?: string;
  readonly type?: string;
}

Schemas

Schema

unstable

Since v4.0.6

The lenient codec for problem details objects.

Details

Decoding follows RFC 9457: a missing type defaults to about:blank, standard members with the wrong JSON type are ignored, and unknown members are kept as extensions. Encoding always emits type.

Signature

declare const Schema: Schema_.Codec<ProblemDetails, ProblemDetailsEncoded>

Example Decoding a problem with an extension

import { Schema } from "effect"
import { ProblemDetails } from "effect/http"

const problem = Schema.decodeUnknownSync(ProblemDetails.Schema)({
  status: 404,
  detail: "No such user",
  traceId: "abc-123"
})
problem // => { type: "about:blank", status: 404, detail: "No such user", traceId: "abc-123" }