일관된 error response를 설계하고 validation 오류를 어떻게 보고하는가?

Question

IT Interview Practice · Accepted Answer

좋은 error response는 두 가지를 한다: **올바른 HTTP status code**(기계가 읽는 신호)를 쓰고, 개발자가 대응할 수 있는 **일관되고 구조화된 body**를 반환한다. 일관성 없는 error 형태는 client 측 고통의 가장 큰 원천 중 하나다.

## 표준 error 형식을 쓰라: RFC 7807 (problem+json)

RFC 7807은 전용 media type을 가진 표준 "problem details" body를 정의하므로, API 전반의 모든 error가 똑같아 보인다:

```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` — error 범주를 식별하는 URI(문서로 역참조 가능).
- `title` — 짧고 사람이 읽을 수 있는 요약(`type`마다 안정적).
- `status` — HTTP status, 편의를 위해 반복.
- `detail` — *이번* 발생에 대한 구체적 설명.
- `instance` — 어느 request/리소스에서 일어났는지.

## validation 오류: 한 번에 모두 보고하라

form/field validation에는 `422`(또는 `400`)와 **field 오류 배열**을 반환해, client가 한 번에 모든 잘못된 field를 강조할 수 있게 하라 — 한 번에 하나씩이 아니라:

```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" }
  ]
}
```

## 원칙

```text
✓ Same body shape for every error (one code path on the client)
✓ A stable machine-readable code (type/code) — clients branch on this, not on prose
✓ Human-readable message for developers/logs
✗ Never leak stack traces, SQL, or internal paths to clients
```

## 왜 중요한가

error 설계는 API가 현실에서 조용히 성공하거나 실패하는 지점이다: happy path는 쉽지만, 소비자는 디버깅 시간의 대부분을 error 경로에서 보내고, 일관성 없거나 모호한 error 계약은 통합을 비참하게 만든다. 면접관은 이를 통해 두 가지를 확인한다. 첫째, **status code와 구조화된 body가 함께 작동하는지** — status는 도구와 retry를 위한 거친 신호, body는 실행 가능한 세부를 담는다 — 오류를 안에 담은 `200 OK` 안티패턴이 아니라. 둘째, **안정적이고 기계가 읽을 수 있는 error code**(RFC 7807의 `type`이나 `code` 필드를 통해)로, client가 다시 쓰이거나 현지화될 수 있는 영어 메시지를 문자열 매칭하는 대신 `"insufficient_funds"`로 분기할 수 있게 하는지. 모든 validation 오류를 한 번에 반환하고, stack trace 같은 내부 세부를 절대 유출하지 않는 것이, 다른 팀이 실제로 소비해야 했던 API를 만들어 본 사람임을 보여 주는 답을 완성한다.

표준 error 형식을 쓰라: RFC 7807 (problem+json)

validation 오류: 한 번에 모두 보고하라

원칙

왜 중요한가

관련 질문