Skip to content

O envelope de erro ​

O Kata produz um único formato de erro. Toda resposta 4xx e 5xx — falhas de validação, seus próprios erros de domínio, output mismatches, throws não capturados — é o mesmo envelope JSON:

ts
type ErrorBody = {
  error: string                          // código estável, legível por máquina
  message: string                        // descrição legível por humanos
  issues?: Record<string, FieldIssue[]>  // erros de campo estruturados, indexados pela seção de input
}
  • error — o discriminador no qual um cliente faz switch ('not_found', 'validation_failed', 'internal_error'). Nunca contém uma frase humana.
  • message — uma descrição legível por humanos. Sempre presente.
  • issues — presente apenas quando há erros de campo estruturados (hoje: validação de input).

Isso é imposto pelo runtime, não por convenção. Ambas as pontas de toda route são validadas, e cada modo de falha mapeia para este envelope. Os dois automáticos vêm primeiro; os que você escreve vêm depois.

EstágioQuandoEm caso de falha
Inputantes do handler rodar422 validation_failed
Handler lançaqualquer escape de middleware ou handler500 internal_error
Outputdepois do handler retornar um valor500 internal_output_shape_mismatch (depende do modo)
Seu 4xxvocê faz return c.error(...) / c.json(...)seu status

Uma requisição cujo body é não-vazio mas não é JSON válido é rejeitada antes da etapa de input, com 400 validation_failed (message: "Malformed JSON body"); um body vazio ou ausente é lido como undefined e deixa o schema decidir.

Route desconhecida e método errado: os 404 / 405 embutidos ​

Duas falhas acontecem antes de qualquer um dos estágios acima — nenhuma route casou, então não há schema de input nem handler seu para rodar. O Kata as responde por conta própria, através do mesmo envelope, sem exigir nenhuma configuração.

Uma requisição para um path que nenhuma route declara responde 404:

json
{ "error": "not_found", "message": "Route not found" }

Uma requisição com o método errado em um path que alguma route de fato declara responde 405, com um header Allow listando os métodos que o path aceita:

json
{ "error": "method_not_allowed", "message": "Method not allowed" }

Ambas rodam primeiro a cadeia de middleware global (nível de app) — o mesmo fallback que permite a um cors() global responder um preflight OPTIONS mesmo contra um path que nenhuma rota declara (veja Preflight de CORS para como o preflight de um path registrado é normalmente respondido) — e ambas passam pela mesma etapa final de toda resposta, então o header de correlação X-Request-Id está presente aqui também.

O envelope de validação 422 ​

input é validado antes do seu handler. Em caso de falha o Kata nunca chama o handler — ele responde 422 com error: "validation_failed", a message "Request input validation failed" e um objeto issues indexado pela seção de input que falhou (params / query / body / headers). Cada chave contém um array de field issues.

Para o body { "name": "", "email": "not-an-email" } de POST /users contra o CreateUserBodySchema, a resposta é (este formato é verificado pelo users.hurl de examples/hello; as strings literais de message são do Zod):

json
{
  "error": "validation_failed",
  "message": "Request input validation failed",
  "issues": {
    "body": [
      { "path": "name",  "code": "too_small",      "message": "String must contain at least 1 character(s)" },
      { "path": "email", "code": "invalid_string", "message": "Invalid email" }
    ]
  }
}

Uma falha de query tem o mesmo formato, só indexada por query em vez de body. É o que um valor inválido de z.enum(...) produz — o formato mais comum de query — para GET /todos?status=archived contra z.object({ status: z.enum(['open', 'done']) }):

json
{
  "error": "validation_failed",
  "message": "Request input validation failed",
  "issues": {
    "query": [
      {
        "path": "status",
        "code": "invalid_enum_value",
        "message": "Invalid enum value. Expected 'open' | 'done', received 'archived'",
        "received": "archived"
      }
    ]
  }
}

O 422 é fixo, e não é configurável

A validação automática de schema — qualquer seção de input que falhe no safeParse — sempre responde 422. O único 400 automático é um body malformado (não-JSON); veja Pegadinhas. Seu próprio c.error(...) é a única coisa que pode produzir um 400, e não existe opção, hook ou config em defineRoute ou createApp que mude o 422 automático.

Se um contrato que você está implementando exige 400 para o que na verdade é uma falha de schema, a saída é afrouxar o schema de input para que ele sempre faça parse, então checar o formato manualmente no handler e retornar c.error(..., { status: 400 }) você mesmo — trocando a checagem automática por uma manual que controla seu próprio status.

O formato FieldIssue ​

Toda entrada sob issues é um FieldIssue:

ts
type FieldIssue = {
  path: string       // caminho com ponto/colchete: "email", "user.profile.age", "items[1].qty"
  message: string    // mensagem legível por humanos do Zod
  code: string       // código de issue do Zod: "too_small", "invalid_type", "invalid_string", …
  expected?: unknown // presente quando a issue do Zod a carrega (ex.: invalid_type, invalid_enum_value)
  received?: unknown // presente quando a issue do Zod a carrega (ex.: invalid_type, invalid_enum_value)
}

Regras para deixar claras:

  • path usa notação de ponto para objetos aninhados e [n] para índices de array. Um erro no nível raiz tem um path: "" vazio.
  • expected / received aparecem quando a issue do Zod subjacente os carrega (ex.: invalid_type, invalid_enum_value) e são omitidos caso contrário.
  • As issues são reportadas na ordem do código-fonte. Quando mais de uma seção é inválida (por exemplo, tanto params quanto body), cada uma recebe sua própria chave sob issues.

Reutilize o formatador

Se você validar algo por conta própria — um payload de webhook, uma query re-parseada, uma regra entre campos — e quiser que a resposta corresponda exatamente a este formato, formatZodIssues(error: ZodError): FieldIssue[] é exportado de @katajs-framework/core. Construa o envelope com c.error('validation_failed', 'Request input validation failed', { status: 422, issues: { body: formatZodIssues(parsed.error) } }).

Validação de output e internal_output_shape_mismatch ​

Quando seu handler retorna um valor simples (não um Response), o Kata o passa pelo schema output da route antes de serializar. O que acontece em caso de mismatch é definido pelo modo outputValidation da aplicação (ADR-0009):

ModoEm caso de mismatchAmbiente pretendido
strictLoga as issues, retorna 500 internal_output_shape_mismatchdev / test / CI
logLoga as issues, envia os dados do handler sem alteraçãoprodução
offPula a validação de output por completoopt-out crítico para performance

Os três modos traçam a tensão entre capturar bugs e manter-se no ar: strict falha de forma ruidosa, para que um formato errado nunca passe despercebido em dev ou CI; log mantém a produção servindo, permitindo que um desvio benigno se torne uma linha de log em vez de uma interrupção; off remove a checagem por completo onde cada microssegundo conta.

O modo é resolvido uma vez no createApp, a primeira correspondência vence:

  1. o outputValidation explícito passado para createApp,
  2. a env var KATA_OUTPUT_VALIDATION quando ela nomeia um modo válido,
  3. derivado de NODE_ENV — production → log, caso contrário strict.
ts
const app = createApp({ modules: [users], outputValidation: 'strict' })

No modo strict as issues do Zod são logadas no servidor (através do seu logger injetado, se houver um registrado, senão console.error) e a resposta é exatamente:

json
{ "error": "internal_output_shape_mismatch", "message": "Response did not match the declared output schema" }

com status 500. Isso pega "o handler retornou quase o formato certo" antes que chegue a um cliente. No modo log as issues ainda são logadas, mas os dados do handler são enviados sem alteração — um desvio de formato benigno em produção se degrada para uma linha de log em vez de um 500 abrupto. No modo off não há safeParse nem transform do Zod; os dados passam como estão.

O mismatch nunca vaza para o cliente

Em um mismatch strict o cliente recebe o envelope genérico internal_output_shape_mismatch. As issues ofensivas do Zod são logadas apenas no servidor — nomes de campos e o formato interno nunca cruzam a rede.

Throws não capturados: internal_error ​

Um throw que escapa de qualquer middleware ou handler é capturado pela fronteira de erro global do Kata e serializado através do mesmo envelope:

json
{ "error": "internal_error", "message": "Internal server error" }

com status 500 e Content-Type: application/json — nunca a página 500 text/HTML padrão do Hono. Essa fronteira existe para que um bug nunca possa vazar um stack trace ou uma página de erro HTML para um cliente: o erro bruto é logado no servidor, e a mensagem subjacente nunca é exposta ao cliente.

Reserve o throw para bugs genuínos. Para falhas que o cliente deve entender, retorne c.error(...).

Testando isso sem uma route de crash

Exercitar esse caminho exige uma route que sempre lança — mas essa route nunca deve ir para a superfície real da app (um GET /diagnostics/boom acessível em produção). Testando o error boundary sem uma route de crash mostra o padrão: construa a route que lança dentro do arquivo de teste, com o createApp/defineRoute da própria app, e nunca a adicione ao array modules do main.ts.

Status customizados: c.error e c.json ​

Para erros de domínio — not found, forbidden, conflict — retorne um Response do handler. A forma idiomática é c.error(code, message, extra?), que constrói o envelope unificado; c.json(value, status?) é o escape hatch para um formato customizado. Ambos estão disponíveis nos contextos da route e do middleware.

ts
return c.error('not_found', 'No user with that id', { status: 404 })
// → 404  { "error": "not_found", "message": "No user with that id" }

Assinatura de c.error:

ts
c.error(code: string, message: string, extra?: ErrorExtra): Response

type ErrorExtra = {
  status?: number                        // padrão 400
  issues?: Record<string, FieldIssue[]>  // anexa erros de campo estruturados
}
  • O argumento code torna-se o campo error na rede.
  • status vai dentro de extra e tem padrão 400.
  • Anexe erros de campo estruturados via extra.issues (o mesmo formato FieldIssue[] do envelope 422).

A distinção que governa o pipeline de resposta (a mesma de Routes & schemas):

  • retornar um valor → validado contra output, enviado como 200.
  • retornar c.error(...) / c.json(body, status) → carrega seu próprio status.

Respostas retornadas e o schema output ​

Com um único schema output, um Response retornado (incluindo c.error) faz um short-circuit na route e não é checado contra ele — que é exatamente o motivo pelo qual é permitido que um body de erro difira do seu formato de sucesso.

ts
export const getUserRoute = defineRoute({
  method: 'GET',
  path: '/users/:id',
  input: { params: z.object({ id: z.string() }) },
  output: UserSchema,
  handler: async (c) => {
    const user = await getUser(c.input.params.id)
    if (!user) return c.error('not_found', 'User not found', { status: 404 }) // não validado
    return user                                                               // validado contra UserSchema
  },
})

Para tipar e validar bodies de erro também, declare output como um mapa status→schema (ADR-0011). O Kata fornece ErrorBodySchema exatamente para isso — o espelho em Zod do envelope unificado:

ts
import { ErrorBodySchema } from '@katajs-framework/core'

export const getUserRoute = defineRoute({
  method: 'GET',
  path: '/users/:id',
  input: { params: GetUserParamsSchema },
  output: { 200: UserSchema, 404: ErrorBodySchema },
  handler: async (c) => {
    const user = await getUser(c.input.params.id)
    if (!user) return c.error('not_found', 'User not found', { status: 404 })
    return user
  },
})

Na forma de mapa: um return simples é o body 200; c.json(body, 201) é validado contra output[201]; um c.error(...) cujo status está declarado é validado contra o schema daquele status. Status não declarados ainda passam adiante sem validação. O Response original é encaminhado literalmente em caso de sucesso — o Kata nunca re-serializa uma resposta que seu handler construiu, então um header ou content type que você definiu é preservado. O cliente RPC faz o narrow por status: InferResponseType<call, 404>. Veja defineRoute para o contrato completo de output.

O schema errado atrás de um status de erro quebra aquele erro em silêncio

Declarar um status o inscreve na validação, e o c.error(...) sempre emite o envelope unificado { error, message }. Então, se o schema sob uma chave 4xx for qualquer outra coisa — o DTO de sucesso, copiado da linha de cima por descuido —, o envelope falha no próprio schema declarado, e o que quem chamou recebe passa a depender do modo, não do seu handler:

ts
output: { 200: TodoSchema, 400: TodoSchema }   // ← 400 não é o envelope
handler: (c) => c.error('invalid_filter', 'Filtro desconhecido', { status: 400 }),
  • strict (o padrão fora de produção) — seu 400 é trocado por 500 { "error": "internal_output_shape_mismatch", … }. O erro de domínio nunca chega a quem chamou.
  • log (o padrão em produção) — o 400 malformado vai para quem chamou como está, e só uma linha de log no servidor registra o descasamento.

Nenhum dos dois modos é o comportamento que você queria, e justamente o que esconde o problema é o que roda em produção. Coloque o ErrorBodySchema — ou um refinamento dele — atrás de todo 4xx/5xx declarado, e o descasamento vira problema de compilação em vez de problema de runtime.

O que é automático vs. o que você escreve ​

SituaçãoStatusQuem produz
Nenhuma route casa com o path404Kata (automático)
O path casa, mas o método não405Kata (automático)
Input falha em seu schema422Kata (automático)
Handler retorna um valor que corresponde ao output200Kata
Handler retorna c.error(...) / c.json(body, status)seu statusvocê
Valor de retorno do handler falha no output500 (depende do modo)Kata (automático)
Handler lança500fronteira de erro do Kata

Pegadinhas ​

  • Um body JSON malformado retorna 400 validation_failed (message: "Malformed JSON body") antes da validação de schema — os bytes inválidos nunca chegam ao seu schema body. Um body vazio ou ausente é diferente: ele é lido como undefined, então o schema body decide (um body opcional passa; um obrigatório → 422).
  • Toda resposta carrega um id de correlação. Sucesso ou erro, o Kata ecoa um header X-Request-Id (reutilizando um header de entrada bem-formado, caso contrário um UUID novo). Veja Ciclo de vida.
  • status não é um argumento posicional em c.error. Ele vive dentro de extra e tem padrão 400 — c.error('not_found', '…') sem um status retorna 400, não 404.

Veja também ​

Código aberto — licença a definir. Feito com Hono + Zod.