구조화된 오류 응답 — 실패까지 계약으로 만들기

# FastAPI — 구조화 envelope 가진 custom 예외 handler
from fastapi import FastAPI, Request, HTTPException, status
from fastapi.responses import JSONResponse
from fastapi.exceptions import RequestValidationError
import uuid

app = FastAPI()

class APIError(Exception):
    def __init__(self, status_code: int, code: str, message: str, **extras):
        self.status_code = status_code
        self.code = code
        self.message = message
        self.extras = extras

@app.exception_handler(APIError)
async def api_error_handler(request: Request, exc: APIError):
    request_id = request.headers.get('x-request-id', str(uuid.uuid4()))
    return JSONResponse(
        status_code=exc.status_code,
        content={
            'error': {
                'code': exc.code,
                'message': exc.message,
                'request_id': request_id,
                **exc.extras,
            }
        },
        headers={'X-Request-ID': request_id},
    )

@app.exception_handler(RequestValidationError)
async def validation_handler(request: Request, exc: RequestValidationError):
    request_id = request.headers.get('x-request-id', str(uuid.uuid4()))
    errors = [
        {
            'field': '.'.join(str(p) for p in e['loc'][1:]),
            'code': e['type'],
            'message': e['msg'],
        }
        for e in exc.errors()
    ]
    return JSONResponse(
        status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
        content={
            'error': {
                'code': 'validation_failed',
                'message': f'필드 {len(errors)} 개에 대한 request validation 실패.',
                'errors': errors,
                'request_id': request_id,
            }
        },
        headers={'X-Request-ID': request_id},
    )

# 이제 handler 에서:
@app.get('/users/{uid}')
async def read_user(uid: str):
    user = await db_find(uid)
    if user is None:
        raise APIError(
            status_code=404,
            code='user_not_found',
            message=f'id {uid} 의 user 없음.',
            user_id=uid,
        )
    return user

# Client — code 에서 분기, 절대 message 에서 안 함
import httpx

def call(method: str, url: str, **kwargs):
    resp = httpx.request(method, url, **kwargs)
    if resp.is_error:
        body = resp.json().get('error', {})
        code = body.get('code')
        if code == 'user_not_found':
            return None  # missing 으로 다룸
        if code == 'validation_failed':
            errors_by_field = {e['field']: e for e in body.get('errors', [])}
            raise UserInputError(errors_by_field)
        if code == 'rate_limited':
            wait = int(resp.headers.get('Retry-After', 1))
            time.sleep(wait)
            return call(method, url, **kwargs)
        # 알 수 없는 error — support escalation 위해 request_id 로그
        raise UnknownAPIError(
            code or f'http_{resp.status_code}',
            body.get('message', resp.text),
            request_id=body.get('request_id'),
        )
    return resp.json()

// RFC 7807 Problem Details — 표준 선호하는 API 용
// Content-Type: application/problem+json

// 단일-error problem
{
  "type":     "https://api.example.com/errors/user-not-found",
  "title":    "User not found",
  "status":   404,
  "detail":   "id u_42 의 user 없음.",
  "instance": "/users/u_42"
}

// 필드 당 detail 가진 validation problem (extension member)
{
  "type":     "https://api.example.com/errors/validation-failed",
  "title":    "Request validation 실패",
  "status":   422,
  "detail":   "필드 3개에 validation 실패.",
  "instance": "/users",
  "errors":   [
    {"field": "email",    "code": "invalid_format"},
    {"field": "password", "code": "too_short", "min": 8},
    {"field": "age",      "code": "out_of_range", "min": 0}
  ]
}