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:
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ágio | Quando | Em caso de falha |
|---|---|---|
| Input | antes do handler rodar | 422 validation_failed |
| Handler lança | qualquer escape de middleware ou handler | 500 internal_error |
| Output | depois do handler retornar um valor | 500 internal_output_shape_mismatch (depende do modo) |
| Seu 4xx | você 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:
{ "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:
{ "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):
{
"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']) }):
{
"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:
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:
pathusa notação de ponto para objetos aninhados e[n]para índices de array. Um erro no nível raiz tem umpath: ""vazio.expected/receivedaparecem 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
paramsquantobody), cada uma recebe sua própria chave sobissues.
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):
| Modo | Em caso de mismatch | Ambiente pretendido |
|---|---|---|
strict | Loga as issues, retorna 500 internal_output_shape_mismatch | dev / test / CI |
log | Loga as issues, envia os dados do handler sem alteração | produção |
off | Pula a validação de output por completo | opt-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:
- o
outputValidationexplícito passado paracreateApp, - a env var
KATA_OUTPUT_VALIDATIONquando ela nomeia um modo válido, - derivado de
NODE_ENV—production→log, caso contráriostrict.
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:
{ "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:
{ "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.
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:
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
codetorna-se o campoerrorna rede. statusvai dentro deextrae tem padrão400.- Anexe erros de campo estruturados via
extra.issues(o mesmo formatoFieldIssue[]do envelope 422).
A distinção que governa o pipeline de resposta (a mesma de Routes & schemas):
- retornar um valor → validado contra
output, enviado como200. - 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.
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:
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:
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) — seu400é trocado por500 { "error": "internal_output_shape_mismatch", … }. O erro de domínio nunca chega a quem chamou.log(o padrão em produção) — o400malformado 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ção | Status | Quem produz |
|---|---|---|
| Nenhuma route casa com o path | 404 | Kata (automático) |
| O path casa, mas o método não | 405 | Kata (automático) |
| Input falha em seu schema | 422 | Kata (automático) |
Handler retorna um valor que corresponde ao output | 200 | Kata |
Handler retorna c.error(...) / c.json(body, status) | seu status | você |
Valor de retorno do handler falha no output | 500 (depende do modo) | Kata (automático) |
| Handler lança | 500 | fronteira de erro do Kata |
Pegadinhas
- Um body JSON malformado retorna
400validation_failed(message: "Malformed JSON body") antes da validação de schema — os bytes inválidos nunca chegam ao seu schemabody. Um body vazio ou ausente é diferente: ele é lido comoundefined, então o schemabodydecide (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. statusnão é um argumento posicional emc.error. Ele vive dentro deextrae tem padrão400—c.error('not_found', '…')sem um status retorna400, não404.
Veja também
defineRoute— o contrato deinput/output.- Cookbook de erros — receitas trabalhadas para retornar seus próprios 4xx.