FastAPI custom exception hierarchy for clean error responses

<p>My FastAPI application raises various exceptions in different layers and I want all errors to return a consistent JSON structure. I also want to map internal exceptions to appropriate HTTP status codes.</p>

<p>Custom exception hierarchy with FastAPI handlers:</p> <div class="highlight"><pre><span></span><code><span class="kn">from</span><span class="w"> </span><span class="nn">fastapi</span><span class="w"> </span><span class="kn">import</span> <span class="n">FastAPI</span><span class="p">,</span> <span class="n">Request</span> <span class="kn">from</span><span class="w"> </span><span class="nn">fastapi.responses</span><span class="w"> </span><span class="kn">import</span> <span class="n">JSONResponse</span> <span class="kn">from</span><span class="w"> </span><span class="nn">fastapi.exceptions</span><span class="w"> </span><span class="kn">import</span> <span class="n">RequestValidationError</span> <span class="c1"># Custom exception hierarchy:</span> <span class="k">class</span><span class="w"> </span><span class="nc">AppError</span><span class="p">(</span><span class="ne">Exception</span><span class="p">):</span> <span class="n">status_code</span><span class="p">:</span> <span class="nb">int</span> <span class="o">=</span> <span class="mi">500</span> <span class="n">code</span><span class="p">:</span> <span class="nb">str</span> <span class="o">=</span> <span class="s1">'internal_error'</span> <span class="k">def</span><span class="w"> </span><span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">message</span><span class="p">:</span> <span class="nb">str</span><span class="p">):</span> <span class="bp">self</span><span class="o">.</span><span class="n">message</span> <span class="o">=</span> <span class="n">message</span> <span class="k">class</span><span class="w"> </span><span class="nc">NotFoundError</span><span class="p">(</span><span class="n">AppError</span><span class="p">):</span> <span class="n">status_code</span><span class="p">,</span> <span class="n">code</span> <span class="o">=</span> <span class="mi">404</span><span class="p">,</span> <span class="s1">'not_found'</span> <span class="k">class</span><span class="w"> </span><span class="nc">ConflictError</span><span class="p">(</span><span class="n">AppError</span><span class="p">):</span> <span class="n">status_code</span><span class="p">,</span> <span class="n">code</span> <span class="o">=</span> <span class="mi">409</span><span class="p">,</span> <span class="s1">'conflict'</span> <span class="k">class</span><span class="w"> </span><span class="nc">ForbiddenError</span><span class="p">(</span><span class="n">AppError</span><span class="p">):</span> <span class="n">status_code</span><span class="p">,</span> <span class="n">code</span> <span class="o">=</span> <span class="mi">403</span><span class="p">,</span> <span class="s1">'forbidden'</span> <span class="k">class</span><span class="w"> </span><span class="nc">UnauthorizedError</span><span class="p">(</span><span class="n">AppError</span><span class="p">):</span> <span class="n">status_code</span><span class="p">,</span> <span class="n">code</span> <span class="o">=</span> <span class="mi">401</span><span class="p">,</span> <span class="s1">'unauthorized'</span> <span class="c1"># Register handlers:</span> <span class="k">def</span><span class="w"> </span><span class="nf">add_exception_handlers</span><span class="p">(</span><span class="n">app</span><span class="p">:</span> <span class="n">FastAPI</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="kc">None</span><span class="p">:</span> <span class="nd">@app</span><span class="o">.</span><span class="n">exception_handler</span><span class="p">(</span><span class="n">AppError</span><span class="p">)</span> <span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">app_error_handler</span><span class="p">(</span><span class="n">request</span><span class="p">:</span> <span class="n">Request</span><span class="p">,</span> <span class="n">exc</span><span class="p">:</span> <span class="n">AppError</span><span class="p">):</span> <span class="k">return</span> <span class="n">JSONResponse</span><span class="p">(</span> <span class="n">status_code</span><span class="o">=</span><span class="n">exc</span><span class="o">.</span><span class="n">status_code</span><span class="p">,</span> <span class="n">content</span><span class="o">=</span><span class="p">{</span><span class="s1">'error'</span><span class="p">:</span> <span class="n">exc</span><span class="o">.</span><span class="n">code</span><span class="p">,</span> <span class="s1">'message'</span><span class="p">:</span> <span class="n">exc</span><span class="o">.</span><span class="n">message</span><span class="p">},</span> <span class="p">)</span> <span class="nd">@app</span><span class="o">.</span><span class="n">exception_handler</span><span class="p">(</span><span class="n">RequestValidationError</span><span class="p">)</span> <span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">validation_handler</span><span class="p">(</span><span class="n">request</span><span class="p">:</span> <span class="n">Request</span><span class="p">,</span> <span class="n">exc</span><span class="p">:</span> <span class="n">RequestValidationError</span><span class="p">):</span> <span class="k">return</span> <span class="n">JSONResponse</span><span class="p">(</span> <span class="n">status_code</span><span class="o">=</span><span class="mi">422</span><span class="p">,</span> <span class="n">content</span><span class="o">=</span><span class="p">{</span><span class="s1">'error'</span><span class="p">:</span> <span class="s1">'validation_error'</span><span class="p">,</span> <span class="s1">'detail'</span><span class="p">:</span> <span class="n">exc</span><span class="o">.</span><span class="n">errors</span><span class="p">()},</span> <span class="p">)</span> <span class="c1"># Usage in service layer:</span> <span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">get_trace_or_404</span><span class="p">(</span><span class="n">session</span><span class="p">,</span> <span class="n">trace_id</span><span class="p">):</span> <span class="n">trace</span> <span class="o">=</span> <span class="k">await</span> <span class="n">session</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="n">Trace</span><span class="p">,</span> <span class="n">trace_id</span><span class="p">)</span> <span class="k">if</span> <span class="ow">not</span> <span class="n">trace</span><span class="p">:</span> <span class="k">raise</span> <span class="n">NotFoundError</span><span class="p">(</span><span class="sa">f</span><span class="s1">'Trace </span><span class="si">{</span><span class="n">trace_id</span><span class="si">}</span><span class="s1"> not found'</span><span class="p">)</span> <span class="k">return</span> <span class="n">trace</span> </code></pre></div> <p>Key points: - Custom hierarchy lets you except AppError to catch any app error - Never expose internal error details (stack traces, DB errors) in production - FastAPI's built-in 422 handler can be overridden for custom format - Use specific subclasses in route handlers for clear intent</p>