Padrões de Resposta de Erro

Q: Problem Details ou envelope customizado?

Problem Details para APIs públicas e parceiros. { error: { code } } interno OK se documentado e consistente.

Q: Como os clientes lidam com códigos desconhecidos?

Use uma mensagem genérica como fallback via prefixo i18nKey errors.unknown e registre o code para suporte.

Q: Manipulador de erros Fastify?

setErrorHandler mapeia AppError para Problem Details - os mesmos tipos do middleware Express.

Q: Filtros de exceção NestJS?

O filtro @Catch(AppError) retorna Problem Details; registre globalmente.

Q: Incluir requestId em erros?

Sim, como campo de extensão requestId - ajuda o suporte a correlacionar o relatório do usuário com os logs.

Q: Documentar erros no OpenAPI?

Sim - responses.404.content.application/problem+json.schema com enum code onde finito.

Q: Erros que podem ser retentados?

Adicione a extensão retryable: true para 503/429 com cabeçalho Retry-After.

Q: Detalhes sensíveis em 403?

Evite "usuário existe, mas tenant errado". Use FORBIDDEN genérico para evitar enumeração.

Q: Falhas de jobs de worker?

Mesmo code no payload do resultado do job; o adaptador HTTP e o worker compartilham os tipos AppError.

Respostas de erro consistentes ajudam os clientes da API a ramificar por code, exibir mensagens localizadas e registrar incidentes. RFC 9457 Problem Details (application/problem+json) é o envelope padrão; códigos de erro estáveis sobrevivem a alterações de cópia.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

// application/errors.ts
export class AppError extends Error {
  constructor(
    public readonly code: string,
    public readonly status: number,
    public readonly detail?: string,
    public readonly i18nKey?: string
  ) {
    super(detail ?? code);
  }
}
 
// infrastructure/http/problem.ts
export function toProblem(err: AppError) {
  return {
    type: `https://api.example.com/errors/${err.code}`,
    title: err.code,
    status: err.status,
    detail: err.detail,
    code: err.code,
    i18nKey: err.i18nKey ?? `errors.${err.code}`,
  };
}

HTTP/1.1 404 Not Found
Content-Type: application/problem+json
 
{
  "type": "https://api.example.com/errors/ORDER_NOT_FOUND",
  "title": "ORDER_NOT_FOUND",
  "status": 404,
  "detail": "Order ord_99 not found",
  "code": "ORDER_NOT_FOUND",
  "i18nKey": "errors.order_not_found"
}

Quando usar isso:

Clientes móveis e web mapeiam erros para strings de UI
Equipes de suporte pesquisam logs por code, não por texto da mensagem
API B2B pública documenta o catálogo de erros no OpenAPI
Você precisa de uma forma consistente entre Express, workers e webhooks

Exemplo de Trabalho

// src/errors/app-error.ts
export class AppError extends Error {
  constructor(
    public readonly code: string,
    public readonly status: number,
    public readonly detail?: string,
    public readonly meta?: Record<string, unknown>
  ) {
    super(detail ?? code);
    this.name = "AppError";
  }
}
 
export class NotFoundError extends AppError {
  constructor(resource: string, id: string) {
    super("NOT_FOUND", 404, `${resource} ${id} not found`, { resource, id });
  }
}
 
// src/http/problem.ts
import type { AppError } from "../errors/app-error";
 
export type ProblemDetails = {
  type: string;
  title: string;
  status: number;
  detail?: string;
  code: string;
  i18nKey: string;
  meta?: Record<string, unknown>;
};
 
const ERROR_BASE = "https://api.acme.example/errors";
 
export function toProblem(err: AppError): ProblemDetails {
  return {
    type: `${ERROR_BASE}/${err.code}`,
    title: err.code,
    status: err.status,
    detail: err.detail,
    code: err.code,
    i18nKey: `errors.${err.code.toLowerCase()}`,
    meta: err.meta,
  };
}
 
// src/http/error-middleware.ts
import type { ErrorRequestHandler } from "express";
import { AppError } from "../errors/app-error";
import { toProblem } from "./problem";
 
export const errorMiddleware: ErrorRequestHandler = (err, req, res, _next) => {
  if (err instanceof AppError) {
    const problem = toProblem(err);
    return res.status(err.status).type("application/problem+json").json(problem);
  }
 
  req.log?.error({ err }, "unhandled error");
  const status = 500;
  res.status(status).type("application/problem+json").json({
    type: `${ERROR_BASE}/INTERNAL_ERROR`,
    title: "INTERNAL_ERROR",
    status,
    code: "INTERNAL_ERROR",
    i18nKey: "errors.internal",
    detail: process.env.NODE_ENV === "production" ? undefined : String(err),
  });
};
 
// use case
import { NotFoundError } from "../errors/app-error";
 
export async function getOrder(repo: { findById: (id: string) => Promise<unknown> }, id: string) {
  const order = await repo.findById(id);
  if (!order) throw new NotFoundError("Order", id);
  return order;
}

O que isso demonstra:

Casos de uso lançam subclasses de AppError com code estável
Um único middleware mapeia todos os erros para JSON Problem Details
Respostas 500 de produção omitem strings de exceção internas
i18nKey permite que os clientes localizem sem analisar o detail em inglês

Mergulho Profundo

Como Funciona

Campos do Problem Details: type (URI), title, status, detail, extensões (code, i18nKey)
Erros de validação adicionam errors[] com extensões field e message
Logging: registre o stack trace completo no servidor; nunca inclua stack no corpo JSON em produção
OpenAPI: documente cada code em responses.4xx.content

Catálogo de Códigos de Erro (Exemplo)

code	HTTP	i18nKey	Quando
`VALIDATION_ERROR`	400	errors.validation	Falha do Zod
`UNAUTHORIZED`	401	errors.unauthorized	Token ausente
`FORBIDDEN`	403	errors.forbidden	Papel insuficiente
`NOT_FOUND`	404	errors.not_found	Recurso ausente
`CONFLICT`	409	errors.conflict	Idempotência duplicada
`RATE_LIMITED`	429	errors.rate_limited	Muitas requisições

Formato de Erro de Validação

{
  "type": "https://api.example.com/errors/VALIDATION_ERROR",
  "title": "VALIDATION_ERROR",
  "status": 400,
  "code": "VALIDATION_ERROR",
  "errors": [
    { "field": "qty", "message": "Number must be greater than 0" }
  ]
}

Notas TypeScript

// Alternativa de tipo Result - erros explícitos sem throw
export type Result<T, E = AppError> = { ok: true; value: T } | { ok: false; error: E };

Armadilhas

Correspondência de strings em detail - Alterações de cópia quebram clientes. Correção: Ramifique apenas em code.
200 com payload de erro - Hack legado de mobile. Correção: Use códigos de status adequados para novas APIs.
Exposição de erros do Prisma - Unique constraint failed on... no corpo. Correção: Mapeie para CONFLICT no middleware.
Formas diferentes por rota - { message } vs { error }. Correção: Um middleware, um esquema.
i18n no servidor - Traduzindo detail no lado do servidor para cada localidade. Correção: Envie i18nKey; o cliente traduz.

Alternativas

Alternativa	Usar Quando	Não Usar Quando
Array de erros GraphQL	API GraphQL	Padrão B2B REST
Envelope `{ error: { code } }`	APIs internas mais simples	Necessidade de ferramentas padrão RFC
Apenas status HTTP	Scripts	UX de cliente rica
Códigos de status gRPC	Serviços gRPC	Clientes REST JSON

FAQs

Problem Details ou envelope customizado?

Problem Details para APIs públicas e parceiros. { error: { code } } interno OK se documentado e consistente.

Validação deve usar 400 ou 422?

Escolha um em toda a organização. 400 é comum; 422 Unprocessable Entity é semanticamente preciso para erros de formato de corpo.

Como os clientes lidam com códigos desconhecidos?

Use uma mensagem genérica como fallback via prefixo i18nKey errors.unknown e registre o code para suporte.

Manipulador de erros Fastify?

setErrorHandler mapeia AppError para Problem Details - os mesmos tipos do middleware Express.

Filtros de exceção NestJS?

O filtro @Catch(AppError) retorna Problem Details; registre globalmente.

Incluir requestId em erros?

Sim, como campo de extensão requestId - ajuda o suporte a correlacionar o relatório do usuário com os logs.

Documentar erros no OpenAPI?

Sim - responses.404.content.application/problem+json.schema com enum code onde finito.

Erros que podem ser retentados?

Adicione a extensão retryable: true para 503/429 com cabeçalho Retry-After.

Detalhes sensíveis em 403?

Evite "usuário existe, mas tenant errado". Use FORBIDDEN genérico para evitar enumeração.

Falhas de jobs de worker?

Mesmo code no payload do resultado do job; o adaptador HTTP e o worker compartilham os tipos AppError.

Relacionados

Noções Básicas de Design de API - envelopes e códigos de status
OpenAPI & Swagger - documente esquemas de erro
Tratamento de Erros no Express - ordem do middleware
Segurança - vazamento seguro de erros
Noções Básicas de Logging - registre erros com contexto

Versões do Stack: Esta página foi escrita para Node.js 24.18.0 (Active LTS), npm 10+, TypeScript 5.6+, Express 5, Fastify 5 e NestJS 11.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

// application/errors.ts
export class AppError extends Error {
  constructor(
    public readonly code: string,
    public readonly status: number,
    public readonly detail?: string,
    public readonly i18nKey?: string
  ) {
    super(detail ?? code);
  }
}
 
// infrastructure/http/problem.ts
export function toProblem(err: AppError) {
  return {
    type: `https://api.example.com/errors/${err.code}`,
    title: err.code,
    status: err.status,
    detail: err.detail,
    code: err.code,
    i18nKey: err.i18nKey ?? `errors.${err.code}`,
  };
}

HTTP/1.1 404 Not Found
Content-Type: application/problem+json
 
{
  "type": "https://api.example.com/errors/ORDER_NOT_FOUND",
  "title": "ORDER_NOT_FOUND",
  "status": 404,
  "detail": "Order ord_99 not found",
  "code": "ORDER_NOT_FOUND",
  "i18nKey": "errors.order_not_found"
}

Quando usar isso:

Clientes móveis e web mapeiam erros para strings de UI
Equipes de suporte pesquisam logs por code, não por texto da mensagem
API B2B pública documenta o catálogo de erros no OpenAPI
Você precisa de uma forma consistente entre Express, workers e webhooks

Exemplo de Trabalho

// src/errors/app-error.ts
export class AppError extends Error {
  constructor(
    public readonly code: string,
    public readonly status: number,
    public readonly detail?: string,
    public readonly meta?: Record<string, unknown>
  ) {
    super(detail ?? code);
    this.name = "AppError";
  }
}
 
export class NotFoundError extends AppError {
  constructor(resource: string, id: string) {
    super("NOT_FOUND", 404, `${resource} ${id} not found`, { resource, id });
  }
}
 
// src/http/problem.ts
import type { AppError } from "../errors/app-error";
 
export type ProblemDetails = {
  type: string;
  title: string;
  status: number;
  detail?: string;
  code: string;
  i18nKey: string;
  meta?: Record<string, unknown>;
};
 
const ERROR_BASE = "https://api.acme.example/errors";
 
export function toProblem(err: AppError): ProblemDetails {
  return {
    type: `${ERROR_BASE}/${err.code}`,
    title: err.code,
    status: err.status,
    detail: err.detail,
    code: err.code,
    i18nKey: `errors.${err.code.toLowerCase()}`,
    meta: err.meta,
  };
}
 
// src/http/error-middleware.ts
import type { ErrorRequestHandler } from "express";
import { AppError } from "../errors/app-error";
import { toProblem } from "./problem";
 
export const errorMiddleware: ErrorRequestHandler = (err, req, res, _next) => {
  if (err instanceof AppError) {
    const problem = toProblem(err);
    return res.status(err.status).type("application/problem+json").json(problem);
  }
 
  req.log?.error({ err }, "unhandled error");
  const status = 500;
  res.status(status).type("application/problem+json").json({
    type: `${ERROR_BASE}/INTERNAL_ERROR`,
    title: "INTERNAL_ERROR",
    status,
    code: "INTERNAL_ERROR",
    i18nKey: "errors.internal",
    detail: process.env.NODE_ENV === "production" ? undefined : String(err),
  });
};
 
// use case
import { NotFoundError } from "../errors/app-error";
 
export async function getOrder(repo: { findById: (id: string) => Promise<unknown> }, id: string) {
  const order = await repo.findById(id);
  if (!order) throw new NotFoundError("Order", id);
  return order;
}

O que isso demonstra:

Casos de uso lançam subclasses de AppError com code estável
Um único middleware mapeia todos os erros para JSON Problem Details
Respostas 500 de produção omitem strings de exceção internas
i18nKey permite que os clientes localizem sem analisar o detail em inglês

Mergulho Profundo

Como Funciona

Campos do Problem Details: type (URI), title, status, detail, extensões (code, i18nKey)
Erros de validação adicionam errors[] com extensões field e message
Logging: registre o stack trace completo no servidor; nunca inclua stack no corpo JSON em produção
OpenAPI: documente cada code em responses.4xx.content

Catálogo de Códigos de Erro (Exemplo)

code	HTTP	i18nKey	Quando
`VALIDATION_ERROR`	400	errors.validation	Falha do Zod
`UNAUTHORIZED`	401	errors.unauthorized	Token ausente
`FORBIDDEN`	403	errors.forbidden	Papel insuficiente
`NOT_FOUND`	404	errors.not_found	Recurso ausente
`CONFLICT`	409	errors.conflict	Idempotência duplicada
`RATE_LIMITED`	429	errors.rate_limited	Muitas requisições

Formato de Erro de Validação

{
  "type": "https://api.example.com/errors/VALIDATION_ERROR",
  "title": "VALIDATION_ERROR",
  "status": 400,
  "code": "VALIDATION_ERROR",
  "errors": [
    { "field": "qty", "message": "Number must be greater than 0" }
  ]
}

Notas TypeScript

// Alternativa de tipo Result - erros explícitos sem throw
export type Result<T, E = AppError> = { ok: true; value: T } | { ok: false; error: E };

Armadilhas

Correspondência de strings em detail - Alterações de cópia quebram clientes. Correção: Ramifique apenas em code.
200 com payload de erro - Hack legado de mobile. Correção: Use códigos de status adequados para novas APIs.
Exposição de erros do Prisma - Unique constraint failed on... no corpo. Correção: Mapeie para CONFLICT no middleware.
Formas diferentes por rota - { message } vs { error }. Correção: Um middleware, um esquema.
i18n no servidor - Traduzindo detail no lado do servidor para cada localidade. Correção: Envie i18nKey; o cliente traduz.

Alternativas

Alternativa	Usar Quando	Não Usar Quando
Array de erros GraphQL	API GraphQL	Padrão B2B REST
Envelope `{ error: { code } }`	APIs internas mais simples	Necessidade de ferramentas padrão RFC
Apenas status HTTP	Scripts	UX de cliente rica
Códigos de status gRPC	Serviços gRPC	Clientes REST JSON

FAQs

Problem Details ou envelope customizado?

Problem Details para APIs públicas e parceiros. { error: { code } } interno OK se documentado e consistente.

Validação deve usar 400 ou 422?

Escolha um em toda a organização. 400 é comum; 422 Unprocessable Entity é semanticamente preciso para erros de formato de corpo.

Como os clientes lidam com códigos desconhecidos?

Use uma mensagem genérica como fallback via prefixo i18nKey errors.unknown e registre o code para suporte.

Manipulador de erros Fastify?

setErrorHandler mapeia AppError para Problem Details - os mesmos tipos do middleware Express.

Filtros de exceção NestJS?

O filtro @Catch(AppError) retorna Problem Details; registre globalmente.

Incluir requestId em erros?

Sim, como campo de extensão requestId - ajuda o suporte a correlacionar o relatório do usuário com os logs.

Documentar erros no OpenAPI?

Sim - responses.404.content.application/problem+json.schema com enum code onde finito.

Erros que podem ser retentados?

Adicione a extensão retryable: true para 503/429 com cabeçalho Retry-After.

Detalhes sensíveis em 403?

Evite "usuário existe, mas tenant errado". Use FORBIDDEN genérico para evitar enumeração.

Falhas de jobs de worker?

Mesmo code no payload do resultado do job; o adaptador HTTP e o worker compartilham os tipos AppError.

Relacionados

Noções Básicas de Design de API - envelopes e códigos de status
OpenAPI & Swagger - documente esquemas de erro
Tratamento de Erros no Express - ordem do middleware
Segurança - vazamento seguro de erros
Noções Básicas de Logging - registre erros com contexto

Versões do Stack: Esta página foi escrita para Node.js 24.18.0 (Active LTS), npm 10+, TypeScript 5.6+, Express 5, Fastify 5 e NestJS 11.

Padrões de Resposta de Erro

Buscar na documentação

Padrões de Resposta de Erro