Como você projeta error responses consistentes e reporta erros de validação?

Question

IT Interview Practice · Accepted Answer

Uma boa error response faz duas coisas: usa o **status code HTTP certo** (o sinal legível por máquina), e retorna um **body estruturado e consistente** sobre o qual um desenvolvedor pode agir. Formatos de erro inconsistentes são uma das maiores fontes de dor do lado do client.

## Use um formato de erro padrão: RFC 7807 (problem+json)

A RFC 7807 define um body "problem details" padrão com um media type dedicado, para que todo erro na sua API tenha a mesma aparência:

```http
HTTP/1.1 404 Not Found
Content-Type: application/problem+json

{
  "type": "https://api.example.com/errors/not-found",
  "title": "Resource not found",
  "status": 404,
  "detail": "No user exists with id 999",
  "instance": "/users/999"
}
```

- `type` — uma URI identificando a categoria do erro (dereferenciável para a documentação).
- `title` — um resumo curto, legível por humanos (estável por `type`).
- `status` — o status HTTP, espelhado por conveniência.
- `detail` — uma explicação específica para *esta* ocorrência.
- `instance` — em qual request/recurso ocorreu.

## Erros de validação: reporte todos de uma vez

Para validação de formulário/campo, retorne `422` (ou `400`) e um **array de erros por campo** para que o client possa destacar todo campo inválido de uma vez — não um erro por vez:

```http
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/problem+json

{
  "type": "https://api.example.com/errors/validation",
  "title": "Validation failed",
  "status": 422,
  "errors": [
    { "field": "email", "code": "invalid_format", "message": "must be a valid email" },
    { "field": "age",   "code": "out_of_range",   "message": "must be >= 18" }
  ]
}
```

## Princípios

```text
✓ Mesmo formato de body para todo erro (um único caminho de código no client)
✓ Um código estável e legível por máquina (type/code) — os clients ramificam nisto, não na prosa
✓ Mensagem legível por humanos para desenvolvedores/logs
✗ Nunca vaze stack traces, SQL, ou caminhos internos para os clients
```

## Por que isso importa

O design de erros é onde as APIs silenciosamente têm sucesso ou fracassam no mundo real: o happy path é fácil, mas os consumidores gastam a maior parte do seu tempo de debug no caminho de erro, e um contrato de erro inconsistente ou vago torna a integração miserável. Os entrevistadores usam isto para checar duas coisas. Primeiro, **o status code mais o body estruturado trabalhando juntos** — o status é o sinal grosso para tooling e retries, o body carrega o detalhe acionável — em vez do anti-pattern de `200 OK` com um erro dentro. Segundo, um **código de erro estável e legível por máquina** (via o `type` da RFC 7807 ou um campo `code`) para que os clients possam ramificar em `"insufficient_funds"` em vez de casar strings de uma mensagem em inglês que pode ser reescrita ou localizada. Retornar todos os erros de validação de uma vez, e nunca vazar detalhes internos como stack traces, completa uma resposta que mostra que você construiu APIs que outros times de fato tiveram que consumir.

Use um formato de erro padrão: RFC 7807 (problem+json)

Erros de validação: reporte todos de uma vez

Princípios

Por que isso importa

Perguntas relacionadas