HTTPException

The single class you use to signal HTTP errors from anywhere in your code.

Usage

from zeromcp.exception import HTTPException

if not user.is_admin:
    raise HTTPException(403, 'Admins only')

if not row:
    raise HTTPException(404, 'Not found')

if duplicate:
    raise HTTPException(409, 'Already exists')

Response shape

ExceptionMiddleware catches HTTPException and renders:

{
  "success": false,
  "status": 403,
  "detail": "Admins only"
}

The HTTP status matches the first argument.

Validation errors

Pydantic validation errors are surfaced as HTTPException(422, [...]) — detail is a list of {field, message} objects:

{
  "success": false,
  "status": 422,
  "detail": [
    {"field": "email", "message": "value is not a valid email address"}
  ]
}

Common status codes

Code	Used by 0-mcp for
400	Invalid JSON body, malformed request
401	Authentication required, missing/invalid session
403	Authenticated but forbidden (token invalid, field not allowed, blocked IP, ALLOWED_ORIGINS rejection)
404	Row not found, segment not found, ownership mismatch
405	Method not allowed for this resource
409	Integrity error (duplicate key)
422	Pydantic validation failed
429	Rate limit exceeded
500	Unhandled error in production (sanitized)

🚦

HTTPException is the only "controlled" error. Anything else raised by your handler is logged and turned into a sanitized 500 in production. In DEBUG=True mode, exceptions propagate so you see the stack trace.

0-mcp by Stamatios Stamou Jr — github.com/ssjunior/0-mcp