Error Envelope Design — Give the Client Something to Work With

# FastAPI — custom exception handler with structured envelope
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'Request validation failed for {len(errors)} field(s).',
                'errors': errors,
                'request_id': request_id,
            }
        },
        headers={'X-Request-ID': request_id},
    )

# Now in your handlers:
@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'No user with id {uid}.',
            user_id=uid,
        )
    return user

# Client — branch on code, never on 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  # treat as 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)
        # Unknown error — log request_id for support escalation
        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 — for APIs that prefer the standard
// Content-Type: application/problem+json

// Single-error problem
{
  "type":     "https://api.example.com/errors/user-not-found",
  "title":    "User not found",
  "status":   404,
  "detail":   "No user with id u_42 exists.",
  "instance": "/users/u_42"
}

// Validation problem with per-field detail (extension members)
{
  "type":     "https://api.example.com/errors/validation-failed",
  "title":    "Request validation failed",
  "status":   422,
  "detail":   "Validation failed for 3 fields.",
  "instance": "/users",
  "errors":   [
    {"field": "email",    "code": "invalid_format"},
    {"field": "password", "code": "too_short", "min": 8},
    {"field": "age",      "code": "out_of_range", "min": 0}
  ]
}