Hacktoberfest 2026: los issues que los mantenedores marcaron para octubre, abiertos y aptos para principiantes. Explorar issues de Hacktoberfest

RFC 9457 Problem Details for HttpApi errors

Abierto
  • ¿Algo no está bien?
#9,686 0 comentarios 0 reacciones 0 asignados Ver en GitHub

Los mantenedores suelen responder en 1 día

@effect-bot ya está trabajando en esto.

Desde el 21/10/2026.

  • #9706 de @effect-bot — abierto

Evaluación

Dificultad
5/5
Tiempo estimado
Más de una semana
Aptitud para principiantes
20/100
Tipo de issue
Nueva funcionalidad
Claridad
Bien especificado
Estado de actividad
Estancado
Stack tecnológico
typescript
Área
backend-api-design

Línea de trabajo

Start with packages/effect/src/http-api/HttpApiError.ts and the existing HttpApi middleware, schema, OpenAPI, and client paths named in the proposal. Review linked pull request #9706 and issue #5367 before considering scope; the issue leaves package placement and decode disclosure open. Done means implementing the proposed Problem Details schema, typed errors, opt-in rendering, OpenAPI support, and client decoding while preserving the default empty-body behavior.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

docker-made-me-do-it enhancement

Problem

RFC 9457 (application/problem+json) is the standard JSON format for HTTP API errors. HttpApi doesn't support it, and by default its errors have no body:

  • The built-in errors (HttpApiError.BadRequest, NotFound, and so on) are sent as empty responses (packages/effect/src/http-api/HttpApiError.ts:23-56).
  • When a request fails to decode, the server answers with an empty 400 (HttpApiError.ts:507). The client gets no indication of which field was wrong or why.

You can build Problem Details yourself with HttpApiMiddleware.layerSchemaErrorTransform and HttpApiSchema.asJson({ contentType }). But every project then writes its own schema, picks its own type, title and status defaults, and has to get the RFC's parsing rules right. For example, §3.1 says a member with the wrong JSON type is ignored, not rejected. #5367 asked for this in v3 and was closed with a workaround that re-encoded response bodies in a middleware. The people in that thread noted that the OpenAPI output then had to be patched as well.

Proposal

  1. A ProblemDetails value and Schema:
    • type defaults to about:blank.
    • status, title, detail and instance are optional.
    • Unknown members are kept as extensions.
    • It decodes leniently, as §3.1 requires, and encodes canonically.
    • A way to declare a typed problem: a fixed type URI with typed extension members, usable as an HttpApi error schema with the right status, media type and OpenAPI entry.
  2. An opt-in that renders HttpApi's own errors (decode failures and the built-ins) as Problem Details.
  3. HttpApiClient decodes application/problem+json responses into the declared problem type.
// names illustrative
class OutOfCredit extends ProblemDetails.Type("https://example.com/probs/out-of-credit", {
  status: 403,
  balance: Schema.Number
}) {}

HttpApiEndpoint.post("buy", "/buy", { error: OutOfCredit })

Why in Effect

HttpApi owns both the mapping from errors to responses and the OpenAPI output, so this is the one place where it can be done without post-processing bodies and patching the spec. The format is widely supported elsewhere: ASP.NET Core (AddProblemDetails), Spring (ProblemDetail), and Rust's http-api-problem crate.

Scope

In scope:

  • The value and Schema, typed problems, opt-in rendering, OpenAPI output and client decoding.

Out of scope:

  • application/problem+xml.
  • Changing the default empty-body behaviour without an opt-in.

Open questions

  • Should this live in effect/http, so it can be used without HttpApi, or in effect/http-api?
  • How much should a decode failure reveal by default? The failing path and message help clients, but they also expose details of the schema.
Lenguaje dominante
TypeScript
Estrellas
16.7k
Forks
808
Merge medio
10 h 7 min
PR fusionados (30 d)
808

Preparar el entorno

Este proyecto no incluye contenedor de desarrollo, Dockerfile ni guía de contribución, así que la configuración corre por tu cuenta: empieza por su README y consulta nuestra guía para la primera contribución para los pasos generales.

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de Effect-TS/effect

Todos los issues de Effect-TS/effect

Issues similares

Más issues de TypeScript

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.