Hacktoberfest 2026: le issue che i maintainer hanno segnato per ottobre, aperte e adatte ai principianti. Sfoglia le issue Hacktoberfest

RFC 9457 Problem Details for HttpApi errors

Chiusa
  • Qualcosa non va?
#9,686 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

Una pull request collegata è già stata integrata.

  • #9706 di @effect-bot — integrata

Valutazione

Difficoltà
5/5
Tempo stimato
Più di una settimana
Idoneità per principianti
20/100
Tipo di issue
Funzionalità
Chiarezza
Specificata chiaramente
Stato di attività
Ferma
Stack tecnologico
typescript
Ambito
backend-api-design

Direzione di ricerca

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.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

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.
Lingua principale
TypeScript
Stelle
16.7k
Fork
808
Merge medio
12h 7m
PR unite (30g)
844

Preparare l'ambiente

Questo progetto non fornisce container di sviluppo, Dockerfile né guida per i contributori, quindi l'ambiente è a tuo carico: parti dal suo README e consulta la nostra guida al primo contributo per i passaggi generali.

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di Effect-TS/effect

Tutte le issue di Effect-TS/effect

Issue simili

Altre issue su TypeScript

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.